System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact d2f814baefc15a2ed2036c499ad5dcfdeca8e853:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 37 2e 38 2e 20 20 42  ersion 3.7.8.  B
00b0: 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c 20  y combining all 
00c0: 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20 43  the individual C
00d0: 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74 6f   code files into
00e0: 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c 65   this .** single
00f0: 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 65   large file, the
0100: 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 6e   entire code can
0110: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 20   be compiled as 
0120: 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c 61  a single transla
0130: 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 54  tion.** unit.  T
0140: 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 20  his allows many 
0150: 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f 20  compilers to do 
0160: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 68  optimizations th
0170: 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 0a  at would not be.
0180: 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 74  ** possible if t
0190: 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 6f  he files were co
01a0: 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 6c  mpiled separatel
01b0: 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 20  y.  Performance 
01c0: 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a 20  improvements.** 
01d0: 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 72  of 5% or more ar
01e0: 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e 20  e commonly seen 
01f0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
0200: 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 6e  ompiled as a sin
0210: 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 69  gle.** translati
0220: 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 54  on unit..**.** T
0230: 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c 20  his file is all 
0240: 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d 70  you need to comp
0250: 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f 20  ile SQLite.  To 
0260: 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f 74  use SQLite in ot
0270: 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 2c  her.** programs,
0280: 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 66   you need this f
0290: 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 6c  ile and the "sql
02a0: 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 66  ite3.h" header f
02b0: 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 73  ile that defines
02c0: 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d 6d  .** the programm
02d0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ing interface to
02e0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
02f0: 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 6f  ary.  (If you do
0300: 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74 68   not have .** th
0310: 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 65  e "sqlite3.h" he
0320: 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 6e  ader file at han
0330: 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e 64  d, you will find
0340: 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 64   a copy embedded
0350: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 74   within.** the t
0360: 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ext of this file
0370: 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 42  .  Search for "B
0380: 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65  egin file sqlite
0390: 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 65  3.h" to find the
03a0: 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65   start.** of the
03b0: 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 65   embedded sqlite
03c0: 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 2e  3.h header file.
03d0: 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f 64  ) Additional cod
03e0: 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 6e  e files may be n
03f0: 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 20  eeded.** if you 
0400: 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 74  want a wrapper t
0410: 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c 69  o interface SQLi
0420: 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 6f  te with your cho
0430: 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d 69  ice of programmi
0440: 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e 20  ng.** language. 
0450: 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65  The code for the
0460: 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d 61   "sqlite3" comma
0470: 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 73  nd-line shell is
0480: 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 65   also in a.** se
0490: 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 69  parate file. Thi
04a0: 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20  s file contains 
04b0: 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 68  only code for th
04c0: 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c 69  e core SQLite li
04d0: 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e  brary..*/.#defin
04e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 0a  e SQLITE_CORE 1.
04f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
0500: 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 69  MALGAMATION 1.#i
0510: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 49  fndef SQLITE_PRI
0520: 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51  VATE.# define SQ
0530: 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 61  LITE_PRIVATE sta
0540: 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  tic.#endif.#ifnd
0550: 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20  ef SQLITE_API.# 
0560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50  define SQLITE_AP
0570: 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a 2a  I.#endif./******
0580: 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66  ******** Begin f
0590: 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68 20  ile sqliteInt.h 
05a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32  *******/./*.** 2
05d0: 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35  001 September 15
05e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
05f0: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0600: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0610: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0620: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0630: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0640: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0650: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0660: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
0670: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
0680: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
0690: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
06a0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
06b0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
06c0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
06d0: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
06e0: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
06f0: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0740: 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74 65  ** Internal inte
0750: 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f 6e  rface definition
0760: 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a 2a  s for SQLite..**
0770: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
0780: 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69 6e  ITEINT_H_.#defin
0790: 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a  e _SQLITEINT_H_.
07a0: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64 65  ./*.** These #de
07b0: 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e 61  fines should ena
07c0: 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73 75  ble >2GB file su
07d0: 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20 69  pport on POSIX i
07e0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
07f0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
0800: 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69 74  stem supports it
0810: 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61 63  .  If the OS lac
0820: 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c 65  ks.** large file
0830: 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66 20   support, or if 
0840: 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f 77  the OS is window
0850: 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64 20  s, these should 
0860: 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  be no-ops..**.**
0870: 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20 20   Ticket #2739:  
0880: 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53  The _LARGEFILE_S
0890: 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73 74  OURCE macro must
08a0: 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20 61   appear before a
08b0: 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69 6e  ny.** system #in
08c0: 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c 20  cludes.  Hence, 
08d0: 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63 6f  this block of co
08e0: 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20 76  de must be the v
08f0: 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f 64  ery first.** cod
0900: 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65 20  e in all source 
0910: 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72  files..**.** Lar
0920: 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20  ge file support 
0930: 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64 20  can be disabled 
0940: 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c 49  using the -DSQLI
0950: 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 73  TE_DISABLE_LFS s
0960: 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65 20  witch.** on the 
0970: 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e 64  compiler command
0980: 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73 20   line.  This is 
0990: 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f 75  necessary if you
09a0: 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a 2a   are compiling.*
09b0: 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d 61  * on a recent ma
09c0: 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20 48  chine (ex: Red H
09d0: 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75 20  at 7.2) but you 
09e0: 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20 74  want your code t
09f0: 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e 20  o work.** on an 
0a00: 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28 65  older machine (e
0a10: 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29 2e  x: Red Hat 6.0).
0a20: 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65    If you compile
0a30: 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32 0a   on Red Hat 7.2.
0a40: 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73 20  ** without this 
0a50: 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20 65  option, LFS is e
0a60: 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53 20  nable.  But LFS 
0a70: 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69  does not exist i
0a80: 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a 20  n the kernel.** 
0a90: 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c 20  in Red Hat 6.0, 
0aa0: 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e 27  so the code won'
0ab0: 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c 20  t work.  Hence, 
0ac0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e 61  for maximum bina
0ad0: 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69 74  ry.** portabilit
0ae0: 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d 69  y you should omi
0af0: 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d  t LFS..**.** Sim
0b00: 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f 72  ilar is true for
0b10: 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53 20   Mac OS X.  LFS 
0b20: 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65  is only supporte
0b30: 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39 20  d on Mac OS X 9 
0b40: 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69  and later..*/.#i
0b50: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49 53  fndef SQLITE_DIS
0b60: 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e  ABLE_LFS.# defin
0b70: 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20 20  e _LARGE_FILE   
0b80: 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20 5f      1.# ifndef _
0b90: 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53  FILE_OFFSET_BITS
0ba0: 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49 4c  .#   define _FIL
0bb0: 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36 34  E_OFFSET_BITS 64
0bc0: 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69 6e  .# endif.# defin
0bd0: 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55  e _LARGEFILE_SOU
0be0: 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a  RCE 1.#endif../*
0bf0: 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65 20  .** Include the 
0c00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 68 65  configuration he
0c10: 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 20 27  ader output by '
0c20: 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 77 65  configure' if we
0c30: 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  're using the.**
0c40: 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 64 20   autoconf-based 
0c50: 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 66 20  build.*/.#ifdef 
0c60: 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 4f 4e  _HAVE_SQLITE_CON
0c70: 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 20 22  FIG_H.#include "
0c80: 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 69 66  config.h".#endif
0c90: 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ../*************
0ca0: 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65  * Include sqlite
0cb0: 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 20 6d  Limit.h in the m
0cc0: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49  iddle of sqliteI
0cd0: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
0ce0: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
0cf0: 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c  * Begin file sql
0d00: 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a 2a  iteLimit.h *****
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d30: 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d 61 79  /./*.** 2007 May
0d40: 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74   7.**.** The aut
0d50: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f  hor disclaims co
0d60: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20  pyright to this 
0d70: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e  source code.  In
0d80: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c   place of.** a l
0d90: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72  egal notice, her
0da0: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a  e is a blessing:
0db0: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f  .**.**    May yo
0dc0: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f  u do good and no
0dd0: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61  t evil..**    Ma
0de0: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69  y you find forgi
0df0: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73  veness for yours
0e00: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20  elf and forgive 
0e10: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61  others..**    Ma
0e20: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65  y you share free
0e30: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67  ly, never taking
0e40: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67   more than you g
0e50: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a  ive..**.********
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ea0: 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 66 69  *.** .** This fi
0eb0: 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 69 6f  le defines vario
0ec0: 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 68 61  us limits of wha
0ed0: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 72 6f  t SQLite can pro
0ee0: 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  cess..*/../*.** 
0ef0: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
0f00: 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f 72 20  th of a TEXT or 
0f10: 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 20 20  BLOB in bytes.  
0f20: 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 6c 69   This also.** li
0f30: 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66  mits the size of
0f40: 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 62 6c   a row in a tabl
0f50: 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a 0a 2a  e or index..**.*
0f60: 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d 69 74  * The hard limit
0f70: 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 79 20   is the ability 
0f80: 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
0f90: 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 74 6f  ed integer.** to
0fa0: 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a 65 3a   count the size:
0fb0: 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 37 34   2^31-1 or 21474
0fc0: 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 64 65  83647..*/.#ifnde
0fd0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e  f SQLITE_MAX_LEN
0fe0: 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  GTH.# define SQL
0ff0: 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 20 31  ITE_MAX_LENGTH 1
1000: 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 69 66  000000000.#endif
1010: 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  ../*.** This is 
1020: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
1030: 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 20 2a  er of.**.**    *
1040: 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   Columns in a ta
1050: 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75  ble.**    * Colu
1060: 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
1070: 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e 73 20  **    * Columns 
1080: 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 20 20  in a view.**    
1090: 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20 53  * Terms in the S
10a0: 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 6e 20  ET clause of an 
10b0: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
10c0: 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69  .**    * Terms i
10d0: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
10e0: 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61   of a SELECT sta
10f0: 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a 20 54  tement.**    * T
1100: 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 4f 55  erms in the GROU
1110: 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 42 59  P BY or ORDER BY
1120: 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 53 45   clauses of a SE
1130: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a  LECT statement..
1140: 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69 6e  **    * Terms in
1150: 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61 75   the VALUES clau
1160: 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54 20  se of an INSERT 
1170: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  statement.**.** 
1180: 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c  The hard upper l
1190: 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 32 36  imit here is 326
11a0: 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 62 61  76.  Most databa
11b0: 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c 0a 2a  se people will.*
11c0: 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 74 20  * tell you that 
11d0: 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d 61 6c  in a well-normal
11e0: 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c 20 79  ized database, y
11f0: 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f 75 6c  ou usually shoul
1200: 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 6d 6f  d.** not have mo
1210: 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 6e 20  re than a dozen 
1220: 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 69 6e  or so columns in
1230: 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 6e 64   any table.  And
1240: 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 20 74   if.** that is t
1250: 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 20 69  he case, there i
1260: 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 68 61  s no point in ha
1270: 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 61  ving more than a
1280: 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 76 61   few.** dozen va
1290: 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 20 74  lues in any of t
12a0: 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 74 69  he other situati
12b0: 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61 62  ons described ab
12c0: 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ove..*/.#ifndef 
12d0: 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d  SQLITE_MAX_COLUM
12e0: 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  N.# define SQLIT
12f0: 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 30 30  E_MAX_COLUMN 200
1300: 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  0.#endif../*.** 
1310: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1320: 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 53  th of a single S
1330: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1340: 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  bytes..**.** It 
1350: 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20 63  used to be the c
1360: 61 73 65 20 74 68 61 74 20 73 65 74 74 69 6e 67  ase that setting
1370: 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f 20 7a   this value to z
1380: 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 75 72  ero would.** tur
1390: 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 66 2e  n the limit off.
13a0: 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c 6f 6e    That is no lon
13b0: 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 69 73  ger true.  It is
13c0: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a 2a 2a   not possible.**
13d0: 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 6c 69   to turn this li
13e0: 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 66 6e  mit off..*/.#ifn
13f0: 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53  def SQLITE_MAX_S
1400: 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 66 69  QL_LENGTH.# defi
1410: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51  ne SQLITE_MAX_SQ
1420: 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 30 30  L_LENGTH 1000000
1430: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  000.#endif../*.*
1440: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  * The maximum de
1450: 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 65 73  pth of an expres
1460: 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 73 20  sion tree. This 
1470: 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 0a 2a  is limited to .*
1480: 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62 79  * some extent by
1490: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c 5f   SQLITE_MAX_SQL_
14a0: 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f 6d 65  LENGTH. But some
14b0: 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 20 0a  time you might .
14c0: 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 63 65  ** want to place
14d0: 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c 69 6d   more severe lim
14e0: 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 6c  its on the compl
14f0: 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a 2a 20  exity of an .** 
1500: 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a 0a 2a  expression..**.*
1510: 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20 75  * A value of 0 u
1520: 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 61 74  sed to mean that
1530: 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 6e   the limit was n
1540: 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a 2a 20  ot enforced..** 
1550: 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f 20 6c  But that is no l
1560: 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 68 65  onger true.  The
1570: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 73 74   limit is now st
1580: 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 64 0a  rictly enforced.
1590: 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 73 2e  ** at all times.
15a0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
15b0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54  TE_MAX_EXPR_DEPT
15c0: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  H.# define SQLIT
15d0: 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54 48  E_MAX_EXPR_DEPTH
15e0: 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a   1000.#endif../*
15f0: 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20  .** The maximum 
1600: 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
1610: 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
1620: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a  LECT statement..
1630: 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 6e 65  ** The code gene
1640: 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 6f 75  rator for compou
1650: 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
1660: 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a 2a 2a  ents does one.**
1670: 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 72 73   level of recurs
1680: 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 65 72  ion for each ter
1690: 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 65 72  m.  A stack over
16a0: 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c 74 0a  flow can result.
16b0: 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 65 72  ** if the number
16c0: 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 6f 6f   of terms is too
16d0: 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 61 63   large.  In prac
16e0: 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c 0a 2a  tice, most SQL.*
16f0: 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f 72 65  * never has more
1700: 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 65 72   than 3 or 4 ter
1710: 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c 75 65  ms.  Use a value
1720: 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 6c 65   of 0 to disable
1730: 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 6f 6e  .** any limit on
1740: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
1750: 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
1760: 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a 23 69  nt SELECT..*/.#i
1770: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1780: 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1790: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
17a0: 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  _MAX_COMPOUND_SE
17b0: 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 66 0a  LECT 500.#endif.
17c0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d  ./*.** The maxim
17d0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70 63  um number of opc
17e0: 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 20 70  odes in a VDBE p
17f0: 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 20 63  rogram..** Not c
1800: 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 63 65  urrently enforce
1810: 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  d..*/.#ifndef SQ
1820: 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50  LITE_MAX_VDBE_OP
1830: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1840: 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 35 30  _MAX_VDBE_OP 250
1850: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1860: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   The maximum num
1870: 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
1880: 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e 63 74   to an SQL funct
1890: 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ion..*/.#ifndef 
18a0: 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43 54  SQLITE_MAX_FUNCT
18b0: 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 6e 65  ION_ARG.# define
18c0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43   SQLITE_MAX_FUNC
18d0: 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 65 6e  TION_ARG 127.#en
18e0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d  dif../*.** The m
18f0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1900: 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 65 73   in-memory pages
1910: 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65 20   to use for the 
1920: 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  main database.**
1930: 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 20 74   table and for t
1940: 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 73 2e  emporary tables.
1950: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46    The SQLITE_DEF
1960: 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45 0a  AULT_CACHE_SIZE.
1970: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1980: 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 45 5f  E_DEFAULT_CACHE_
1990: 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51  SIZE.# define SQ
19a0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43  LITE_DEFAULT_CAC
19b0: 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a 23 65  HE_SIZE  2000.#e
19c0: 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c  ndif.#ifndef SQL
19d0: 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 4d 50  ITE_DEFAULT_TEMP
19e0: 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 64 65  _CACHE_SIZE.# de
19f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 41  fine SQLITE_DEFA
1a00: 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 5f 53  ULT_TEMP_CACHE_S
1a10: 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 66 0a  IZE  500.#endif.
1a20: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ./*.** The defau
1a30: 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 72 61  lt number of fra
1a40: 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c 61 74  mes to accumulat
1a50: 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69 6c  e in the log fil
1a60: 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 65 63  e before.** chec
1a70: 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 64 61  kpointing the da
1a80: 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d 6f  tabase in WAL mo
1a90: 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  de..*/.#ifndef S
1aa0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 41  QLITE_DEFAULT_WA
1ab0: 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54  L_AUTOCHECKPOINT
1ac0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1ad0: 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55 54  _DEFAULT_WAL_AUT
1ae0: 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 30 30  OCHECKPOINT  100
1af0: 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  0.#endif../*.** 
1b00: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1b10: 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64  er of attached d
1b20: 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 73 20  atabases.  This 
1b30: 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
1b40: 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 54 68  0.** and 62.  Th
1b50: 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  e upper bound on
1b60: 20 36 32 20 69 73 20 62 65 63 61 75 73 65 20 61   62 is because a
1b70: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1b80: 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 73 65  bitmap.** is use
1b90: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
1ba0: 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 20 64  track attached d
1bb0: 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 69 66  atabases..*/.#if
1bc0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1bd0: 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 69 6e  ATTACHED.# defin
1be0: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54 54  e SQLITE_MAX_ATT
1bf0: 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 66 0a  ACHED 10.#endif.
1c00: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69  ../*.** The maxi
1c10: 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 20 3f  mum value of a ?
1c20: 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 68 61  nnn wildcard tha
1c30: 74 20 74 68 65 20 70 61 72 73 65 72 20 77 69 6c  t the parser wil
1c40: 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 69 66  l accept..*/.#if
1c50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1c60: 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a  VARIABLE_NUMBER.
1c70: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
1c80: 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MAX_VARIABLE_NUM
1c90: 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 0a 0a  BER 999.#endif..
1ca0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 65 20  /* Maximum page 
1cb0: 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 65 72  size.  The upper
1cc0: 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 20 76   bound on this v
1cd0: 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e 20 20  alue is 65536.  
1ce0: 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a 2a 20  This a limit.** 
1cf0: 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 20 75  imposed by the u
1d00: 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f 66 66  se of 16-bit off
1d10: 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 63 68  sets within each
1d20: 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 61 72   page..**.** Ear
1d30: 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  lier versions of
1d40: 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 64 20   SQLite allowed 
1d50: 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 61 6e  the user to chan
1d60: 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 61 74  ge this value at
1d70: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1d80: 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c 6f 6e  . This is no lon
1d90: 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c 20 6f  ger permitted, o
1da0: 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 74 68  n the grounds th
1db0: 61 74 20 69 74 20 63 72 65 61 74 65 73 0a 2a 2a  at it creates.**
1dc0: 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 74 20   a library that 
1dd0: 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 20 69  is technically i
1de0: 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 74 68  ncompatible with
1df0: 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 72 61   an SQLite libra
1e00: 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  ry .** compiled 
1e10: 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e 74  with a different
1e20: 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 72 6f   limit. If a pro
1e30: 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 20 6f  cess operating o
1e40: 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  n a database .**
1e50: 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 69 7a   with a page-siz
1e60: 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 65 73  e of 65536 bytes
1e70: 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e 20 61   crashes, then a
1e80: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 53 51  n instance of SQ
1e90: 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  Lite .** compile
1ea0: 64 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  d with the defau
1eb0: 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c 69 6d  lt page-size lim
1ec0: 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 61  it will not be a
1ed0: 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b 20  ble to rollback 
1ee0: 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 64 20  .** the aborted 
1ef0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
1f00: 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 6f 20  s could lead to 
1f10: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
1f20: 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ion..*/.#ifdef S
1f30: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53  QLITE_MAX_PAGE_S
1f40: 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  IZE.# undef SQLI
1f50: 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45  TE_MAX_PAGE_SIZE
1f60: 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
1f70: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
1f80: 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f 2a 0a  SIZE 65536.../*.
1f90: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 73  ** The default s
1fa0: 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 61 73  ize of a databas
1fb0: 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 6e 64  e page..*/.#ifnd
1fc0: 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  ef SQLITE_DEFAUL
1fd0: 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64 65  T_PAGE_SIZE.# de
1fe0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 41  fine SQLITE_DEFA
1ff0: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 31 30  ULT_PAGE_SIZE 10
2000: 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51  24.#endif.#if SQ
2010: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47  LITE_DEFAULT_PAG
2020: 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f 4d 41  E_SIZE>SQLITE_MA
2030: 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 75 6e  X_PAGE_SIZE.# un
2040: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55  def SQLITE_DEFAU
2050: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64  LT_PAGE_SIZE.# d
2060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
2070: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 53  AULT_PAGE_SIZE S
2080: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53  QLITE_MAX_PAGE_S
2090: 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  IZE.#endif../*.*
20a0: 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 69 66  * Ordinarily, if
20b0: 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 78 70   no value is exp
20c0: 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 65 64  licitly provided
20d0: 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 73  , SQLite creates
20e0: 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 77 69   databases.** wi
20f0: 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 51 4c  th page size SQL
2100: 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47 45  ITE_DEFAULT_PAGE
2110: 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 2c 20  _SIZE. However, 
2120: 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 69 6e  based on certain
2130: 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 72 61  .** device chara
2140: 63 74 65 72 69 73 74 69 63 73 20 28 73 65 63 74  cteristics (sect
2150: 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 6f 6d  or-size and atom
2160: 69 63 20 77 72 69 74 65 28 29 20 73 75 70 70 6f  ic write() suppo
2170: 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  rt),.** SQLite m
2180: 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 72 67  ay choose a larg
2190: 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 20 63  er value. This c
21a0: 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 20 6d  onstant is the m
21b0: 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a 2a 20  aximum value.** 
21c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 6f 6f  SQLite will choo
21d0: 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e 0a 2a  se on its own..*
21e0: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
21f0: 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47  _MAX_DEFAULT_PAG
2200: 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20  E_SIZE.# define 
2210: 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55  SQLITE_MAX_DEFAU
2220: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 31 39  LT_PAGE_SIZE 819
2230: 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c  2.#endif.#if SQL
2240: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f  ITE_MAX_DEFAULT_
2250: 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45  PAGE_SIZE>SQLITE
2260: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23  _MAX_PAGE_SIZE.#
2270: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41   undef SQLITE_MA
2280: 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f 53  X_DEFAULT_PAGE_S
2290: 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  IZE.# define SQL
22a0: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f  ITE_MAX_DEFAULT_
22b0: 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 54 45  PAGE_SIZE SQLITE
22c0: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23  _MAX_PAGE_SIZE.#
22d0: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 4d 61  endif.../*.** Ma
22e0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
22f0: 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 61 74  pages in one dat
2300: 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
2310: 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c 6c 79  * This is really
2320: 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 75 6c   just the defaul
2330: 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  t value for the 
2340: 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 70  max_page_count p
2350: 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 20 76  ragma..** This v
2360: 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f 77 65  alue can be lowe
2370: 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 29 20  red (or raised) 
2380: 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
2390: 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 6d 61  g that the.** ma
23a0: 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d 61 63  x_page_count mac
23b0: 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  ro..*/.#ifndef S
23c0: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43  QLITE_MAX_PAGE_C
23d0: 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 53 51  OUNT.# define SQ
23e0: 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43 4f  LITE_MAX_PAGE_CO
23f0: 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 0a 23  UNT 1073741823.#
2400: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78  endif../*.** Max
2410: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 6e 20  imum length (in 
2420: 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 70 61  bytes) of the pa
2430: 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b 45 20  ttern in a LIKE 
2440: 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 72 61  or GLOB.** opera
2450: 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  tor..*/.#ifndef 
2460: 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45 5f  SQLITE_MAX_LIKE_
2470: 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 0a 23  PATTERN_LENGTH.#
2480: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d   define SQLITE_M
2490: 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  AX_LIKE_PATTERN_
24a0: 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 65 6e  LENGTH 50000.#en
24b0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 69 6d  dif../*.** Maxim
24c0: 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
24d0: 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
24e0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 6c 75  rs..**.** A valu
24f0: 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 68 61  e of 1 means tha
2500: 74 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  t a trigger prog
2510: 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  ram will not be 
2520: 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 0a 2a  able to itself.*
2530: 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 67 67  * fire any trigg
2540: 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f 66 20  ers. A value of 
2550: 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20  0 means that no 
2560: 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
2570: 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 79 20   at all .** may 
2580: 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a 2f 0a  be executed..*/.
2590: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
25a0: 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  AX_TRIGGER_DEPTH
25b0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
25c0: 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50  _MAX_TRIGGER_DEP
25d0: 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a  TH 1000.#endif..
25e0: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
25f0: 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c 69 6d  End of sqliteLim
2600: 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  it.h ***********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  **************/.
2630: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
2640: 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 65  Continuing where
2650: 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e 20   we left off in 
2660: 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a  sqliteInt.h ****
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  **************/.
2680: 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 69 73  ./* Disable nuis
2690: 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 6f 6e  ance warnings on
26a0: 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 6c 65   Borland compile
26b0: 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  rs */.#if define
26c0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
26d0: 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 72 63  #pragma warn -rc
26e0: 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 6c 65  h /* unreachable
26f0: 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 6d 61   code */.#pragma
2700: 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 43 6f   warn -ccc /* Co
2710: 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 61 79  ndition is alway
2720: 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65 20  s true or false 
2730: 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20  */.#pragma warn 
2740: 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e 65 64  -aus /* Assigned
2750: 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 72 20   value is never 
2760: 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d 61 20  used */.#pragma 
2770: 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 6f 6d  warn -csu /* Com
2780: 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 61 6e  paring signed an
2790: 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a 23 70  d unsigned */.#p
27a0: 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 61 20  ragma warn -spa 
27b0: 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 70 6f  /* Suspicious po
27c0: 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 69 63  inter arithmetic
27d0: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e   */.#endif../* N
27e0: 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f 75  eeded for variou
27f0: 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e  s definitions...
2800: 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 4e 55   */.#ifndef _GNU
2810: 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 6e 65  _SOURCE.# define
2820: 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65 6e   _GNU_SOURCE.#en
2830: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75  dif../*.** Inclu
2840: 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61 64  de standard head
2850: 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63 65  er files as nece
2860: 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66 20  ssary.*/.#ifdef 
2870: 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23 69  HAVE_STDINT_H.#i
2880: 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e 68  nclude <stdint.h
2890: 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20  >.#endif.#ifdef 
28a0: 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48 0a  HAVE_INTTYPES_H.
28b0: 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79 70  #include <inttyp
28c0: 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  es.h>.#endif../*
28d0: 0a 2a 2a 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  .** The number o
28e0: 66 20 73 61 6d 70 6c 65 73 20 6f 66 20 61 6e 20  f samples of an 
28f0: 69 6e 64 65 78 20 74 68 61 74 20 53 51 4c 69 74  index that SQLit
2900: 65 20 74 61 6b 65 73 20 69 6e 20 6f 72 64 65 72  e takes in order
2910: 20 74 6f 20 0a 2a 2a 20 63 6f 6e 73 74 72 75 63   to .** construc
2920: 74 20 61 20 68 69 73 74 6f 67 72 61 6d 20 6f 66  t a histogram of
2930: 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65   the table conte
2940: 6e 74 20 77 68 65 6e 20 72 75 6e 6e 69 6e 67 20  nt when running 
2950: 41 4e 41 4c 59 5a 45 0a 2a 2a 20 61 6e 64 20 77  ANALYZE.** and w
2960: 69 74 68 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ith SQLITE_ENABL
2970: 45 5f 53 54 41 54 32 0a 2a 2f 0a 23 64 65 66 69  E_STAT2.*/.#defi
2980: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
2990: 53 41 4d 50 4c 45 53 20 31 30 0a 0a 2f 2a 0a 2a  SAMPLES 10../*.*
29a0: 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
29b0: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
29c0: 74 6f 20 63 61 73 74 20 70 6f 69 6e 74 65 72 73  to cast pointers
29d0: 20 74 6f 20 69 6e 74 65 67 65 72 73 20 61 6e 64   to integers and
29e0: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 74 6f 20  .** integers to 
29f0: 70 6f 69 6e 74 65 72 73 2e 20 20 54 68 65 20 77  pointers.  The w
2a00: 61 79 20 79 6f 75 20 64 6f 20 74 68 69 73 20 76  ay you do this v
2a10: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 63  aries from one c
2a20: 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20 74 68  ompiler.** to th
2a30: 65 20 6e 65 78 74 2c 20 73 6f 20 77 65 20 68 61  e next, so we ha
2a40: 76 65 20 64 65 76 65 6c 6f 70 65 64 20 74 68 65  ve developed the
2a50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 74 20 6f   following set o
2a60: 66 20 23 69 66 20 73 74 61 74 65 6d 65 6e 74 73  f #if statements
2a70: 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61 74 65 20  .** to generate 
2a80: 61 70 70 72 6f 70 72 69 61 74 65 20 6d 61 63 72  appropriate macr
2a90: 6f 73 20 66 6f 72 20 61 20 77 69 64 65 20 72 61  os for a wide ra
2aa0: 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c 65 72 73  nge of compilers
2ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 72 72  ..**.** The corr
2ac0: 65 63 74 20 22 41 4e 53 49 22 20 77 61 79 20 74  ect "ANSI" way t
2ad0: 6f 20 64 6f 20 74 68 69 73 20 69 73 20 74 6f 20  o do this is to 
2ae0: 75 73 65 20 74 68 65 20 69 6e 74 70 74 72 5f 74  use the intptr_t
2af0: 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e 66 6f 72   type. .** Unfor
2b00: 74 75 6e 61 74 65 6c 79 2c 20 74 68 61 74 20 74  tunately, that t
2b10: 79 70 65 64 65 66 20 69 73 20 6e 6f 74 20 61 76  ypedef is not av
2b20: 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c 6c 20 63  ailable on all c
2b30: 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a 2a 2a 20  ompilers, or.** 
2b40: 69 66 20 69 74 20 69 73 20 61 76 61 69 6c 61 62  if it is availab
2b50: 6c 65 2c 20 69 74 20 72 65 71 75 69 72 65 73 20  le, it requires 
2b60: 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f 66 20 73  an #include of s
2b70: 70 65 63 69 66 69 63 20 68 65 61 64 65 72 73 0a  pecific headers.
2b80: 2a 2a 20 74 68 61 74 20 76 61 72 79 20 66 72 6f  ** that vary fro
2b90: 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65 20 74 6f  m one machine to
2ba0: 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a   the next..**.**
2bb0: 20 54 69 63 6b 65 74 20 23 33 38 36 30 3a 20 20   Ticket #3860:  
2bc0: 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d 34 2e 32  The llvm-gcc-4.2
2bd0: 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f 6d 20 41   compiler from A
2be0: 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f 6e 0a 2a  pple chokes on.*
2bf0: 2a 20 74 68 65 20 28 28 76 6f 69 64 2a 29 26 28  * the ((void*)&(
2c00: 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 20 63 6f  (char*)0)[X]) co
2c10: 6e 73 74 72 75 63 74 2e 20 20 42 75 74 20 4d 53  nstruct.  But MS
2c20: 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20 28 28 76  VC chokes on ((v
2c30: 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a 20 53 6f  oid*)(X))..** So
2c40: 20 77 65 20 68 61 76 65 20 74 6f 20 64 65 66 69   we have to defi
2c50: 6e 65 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e  ne the macros in
2c60: 20 64 69 66 66 65 72 65 6e 74 20 77 61 79 73 20   different ways 
2c70: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
2c80: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e 0a 2a 2f  .** compiler..*/
2c90: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 50  .#if defined(__P
2ca0: 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 20 20  TRDIFF_TYPE__)  
2cb0: 2f 2a 20 54 68 69 73 20 63 61 73 65 20 73 68 6f  /* This case sho
2cc0: 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20 47 43 43  uld work for GCC
2cd0: 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53 51 4c   */.# define SQL
2ce0: 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58  ITE_INT_TO_PTR(X
2cf0: 29 20 20 28 28 76 6f 69 64 2a 29 28 5f 5f 50 54  )  ((void*)(__PT
2d00: 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29  RDIFF_TYPE__)(X)
2d10: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  ).# define SQLIT
2d20: 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20  E_PTR_TO_INT(X) 
2d30: 20 28 28 69 6e 74 29 28 5f 5f 50 54 52 44 49 46   ((int)(__PTRDIF
2d40: 46 5f 54 59 50 45 5f 5f 29 28 58 29 29 0a 23 65  F_TYPE__)(X)).#e
2d50: 6c 69 66 20 21 64 65 66 69 6e 65 64 28 5f 5f 47  lif !defined(__G
2d60: 4e 55 43 5f 5f 29 20 20 20 20 20 20 20 2f 2a 20  NUC__)       /* 
2d70: 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d 70 69 6c  Works for compil
2d80: 65 72 73 20 6f 74 68 65 72 20 74 68 61 6e 20 4c  ers other than L
2d90: 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20  LVM */.# define 
2da0: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54  SQLITE_INT_TO_PT
2db0: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 26 28  R(X)  ((void*)&(
2dc0: 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 0a 23 20  (char*)0)[X]).# 
2dd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54  define SQLITE_PT
2de0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69  R_TO_INT(X)  ((i
2df0: 6e 74 29 28 28 28 63 68 61 72 2a 29 58 29 2d 28  nt)(((char*)X)-(
2e00: 63 68 61 72 2a 29 30 29 29 0a 23 65 6c 69 66 20  char*)0)).#elif 
2e10: 64 65 66 69 6e 65 64 28 48 41 56 45 5f 53 54 44  defined(HAVE_STD
2e20: 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55 73 65 20  INT_H)   /* Use 
2e30: 74 68 69 73 20 63 61 73 65 20 69 66 20 77 65 20  this case if we 
2e40: 68 61 76 65 20 41 4e 53 49 20 68 65 61 64 65 72  have ANSI header
2e50: 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53 51  s */.# define SQ
2e60: 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 28  LITE_INT_TO_PTR(
2e70: 58 29 20 20 28 28 76 6f 69 64 2a 29 28 69 6e 74  X)  ((void*)(int
2e80: 70 74 72 5f 74 29 28 58 29 29 0a 23 20 64 65 66  ptr_t)(X)).# def
2e90: 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f 54  ine SQLITE_PTR_T
2ea0: 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74 29  O_INT(X)  ((int)
2eb0: 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23  (intptr_t)(X)).#
2ec0: 65 6c 73 65 20 20 20 20 20 20 20 20 20 20 20 20  else            
2ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2ee0: 20 47 65 6e 65 72 61 74 65 73 20 61 20 77 61 72   Generates a war
2ef0: 6e 69 6e 67 20 2d 20 62 75 74 20 69 74 20 61 6c  ning - but it al
2f00: 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f 0a 23 20  ways works */.# 
2f10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2f20: 54 5f 54 4f 5f 50 54 52 28 58 29 20 20 28 28 76  T_TO_PTR(X)  ((v
2f30: 6f 69 64 2a 29 28 58 29 29 0a 23 20 64 65 66 69  oid*)(X)).# defi
2f40: 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f 54 4f  ne SQLITE_PTR_TO
2f50: 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74 29 28  _INT(X)  ((int)(
2f60: 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  X)).#endif../*.*
2f70: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 54 48 52  * The SQLITE_THR
2f80: 45 41 44 53 41 46 45 20 6d 61 63 72 6f 20 6d 75  EADSAFE macro mu
2f90: 73 74 20 62 65 20 64 65 66 69 6e 65 64 20 61 73  st be defined as
2fa0: 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a 2a 2a 20   0, 1, or 2..** 
2fb0: 30 20 6d 65 61 6e 73 20 6d 75 74 65 78 65 73 20  0 means mutexes 
2fc0: 61 72 65 20 70 65 72 6d 61 6e 65 6e 74 6c 79 20  are permanently 
2fd0: 64 69 73 61 62 6c 65 20 61 6e 64 20 74 68 65 20  disable and the 
2fe0: 6c 69 62 72 61 72 79 20 69 73 20 6e 65 76 65 72  library is never
2ff0: 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 65 2e 20  .** threadsafe. 
3000: 20 31 20 6d 65 61 6e 73 20 74 68 65 20 6c 69 62   1 means the lib
3010: 72 61 72 79 20 69 73 20 73 65 72 69 61 6c 69 7a  rary is serializ
3020: 65 64 20 77 68 69 63 68 20 69 73 20 74 68 65 20  ed which is the 
3030: 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65 76 65 6c  highest.** level
3040: 20 6f 66 20 74 68 72 65 61 64 73 61 66 65 74 79   of threadsafety
3050: 2e 20 20 32 20 6d 65 61 6e 73 20 74 68 65 20 6c  .  2 means the l
3060: 69 62 61 72 79 20 69 73 20 6d 75 6c 74 69 74 68  ibary is multith
3070: 72 65 61 64 65 64 20 2d 20 6d 75 6c 74 69 70 6c  readed - multipl
3080: 65 0a 2a 2a 20 74 68 72 65 61 64 73 20 63 61 6e  e.** threads can
3090: 20 75 73 65 20 53 51 4c 69 74 65 20 61 73 20 6c   use SQLite as l
30a0: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
30b0: 72 65 61 64 73 20 74 72 79 20 74 6f 20 75 73 65  reads try to use
30c0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
30d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30e0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
30f0: 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65 72 20 76  e..**.** Older v
3100: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3110: 65 20 75 73 65 64 20 61 6e 20 6f 70 74 69 6f 6e  e used an option
3120: 61 6c 20 54 48 52 45 41 44 53 41 46 45 20 6d 61  al THREADSAFE ma
3130: 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75 70 70 6f  cro..** We suppo
3140: 72 74 20 74 68 61 74 20 66 6f 72 20 6c 65 67 61  rt that for lega
3150: 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69  cy..*/.#if !defi
3160: 6e 65 64 28 53 51 4c 49 54 45 5f 54 48 52 45 41  ned(SQLITE_THREA
3170: 44 53 41 46 45 29 0a 23 69 66 20 64 65 66 69 6e  DSAFE).#if defin
3180: 65 64 28 54 48 52 45 41 44 53 41 46 45 29 0a 23  ed(THREADSAFE).#
3190: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
31a0: 48 52 45 41 44 53 41 46 45 20 54 48 52 45 41 44  HREADSAFE THREAD
31b0: 53 41 46 45 0a 23 65 6c 73 65 0a 23 20 64 65 66  SAFE.#else.# def
31c0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41  ine SQLITE_THREA
31d0: 44 53 41 46 45 20 31 20 2f 2a 20 49 4d 50 3a 20  DSAFE 1 /* IMP: 
31e0: 52 2d 30 37 32 37 32 2d 32 32 33 30 39 20 2a 2f  R-07272-22309 */
31f0: 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a 0a  .#endif.#endif..
3200: 2f 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  /*.** The SQLITE
3210: 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
3220: 55 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 62 65  US macro must be
3230: 20 64 65 66 69 6e 65 64 20 61 73 20 65 69 74 68   defined as eith
3240: 65 72 20 30 20 6f 72 20 31 2e 0a 2a 2a 20 49 74  er 0 or 1..** It
3250: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 74   determines whet
3260: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66  her or not the f
3270: 65 61 74 75 72 65 73 20 72 65 6c 61 74 65 64 20  eatures related 
3280: 74 6f 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  to .** SQLITE_CO
3290: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 61  NFIG_MEMSTATUS a
32a0: 72 65 20 61 76 61 69 6c 61 62 6c 65 20 62 79 20  re available by 
32b0: 64 65 66 61 75 6c 74 20 6f 72 20 6e 6f 74 2e 20  default or not. 
32c0: 54 68 69 73 20 76 61 6c 75 65 20 63 61 6e 0a 2a  This value can.*
32d0: 2a 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  * be overridden 
32e0: 61 74 20 72 75 6e 74 69 6d 65 20 75 73 69 6e 67  at runtime using
32f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   the sqlite3_con
3300: 66 69 67 28 29 20 41 50 49 2e 0a 2a 2f 0a 23 69  fig() API..*/.#i
3310: 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54  f !defined(SQLIT
3320: 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
3330: 54 55 53 29 0a 23 20 64 65 66 69 6e 65 20 53 51  TUS).# define SQ
3340: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
3350: 53 54 41 54 55 53 20 31 0a 23 65 6e 64 69 66 0a  STATUS 1.#endif.
3360: 0a 2f 2a 0a 2a 2a 20 45 78 61 63 74 6c 79 20 6f  ./*.** Exactly o
3370: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
3380: 69 6e 67 20 6d 61 63 72 6f 73 20 6d 75 73 74 20  ing macros must 
3390: 62 65 20 64 65 66 69 6e 65 64 20 69 6e 20 6f 72  be defined in or
33a0: 64 65 72 20 74 6f 0a 2a 2a 20 73 70 65 63 69 66  der to.** specif
33b0: 79 20 77 68 69 63 68 20 6d 65 6d 6f 72 79 20 61  y which memory a
33c0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
33d0: 74 65 6d 20 74 6f 20 75 73 65 2e 0a 2a 2a 0a 2a  tem to use..**.*
33e0: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 53 59 53  *     SQLITE_SYS
33f0: 54 45 4d 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  TEM_MALLOC      
3400: 20 20 20 20 2f 2f 20 55 73 65 20 6e 6f 72 6d 61      // Use norma
3410: 6c 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  l system malloc(
3420: 29 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  ).**     SQLITE_
3430: 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 38 22 0a 23 64 65 66 69     "3.7.8".#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 38  N_NUMBER 3007008
59f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a00: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
5a10: 32 30 31 31 2d 30 37 2d 32 38 20 32 30 3a 34 38  2011-07-28 20:48
5a20: 3a 33 38 20 31 62 35 36 36 37 37 62 64 66 62 31  :38 1b56677bdfb1
5a30: 30 32 64 30 37 30 61 32 30 35 37 61 36 35 62 61  02d070a2057a65ba
5a40: 34 32 34 66 65 63 38 31 31 33 31 64 22 0a 0a 2f  424fec81131d"../
5a50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
5a60: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
5a70: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
5a80: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
5a90: 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71  ite3_version, sq
5aa0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
5ab0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
5ac0: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
5ad0: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
5ae0: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
5af0: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
5b00: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
5b10: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
5b20: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
5b30: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
5b40: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
5b50: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
5b60: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
5b70: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
5b80: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
5b90: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
5ba0: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
5bb0: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
5bc0: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
5bd0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
5be0: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
5bf0: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
5c00: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
5c10: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
5c20: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
5c30: 72 2c 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75  r, and thus insu
5c40: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
5c50: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
5c60: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
5c70: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
5c80: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
5c90: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
5ca0: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
5cb0: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
5cc0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
5cd0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
5ce0: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
5cf0: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
5d00: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
5d10: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
5d20: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
5d30: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
5d40: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
5d50: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
5d60: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
5d70: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
5d80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
5d90: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
5da0: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
5db0: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
5dc0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
5dd0: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
5de0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
5df0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
5e00: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
5e10: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
5e20: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
5e30: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
5e40: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
5e50: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
5e60: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
5e70: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
5e80: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
5e90: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
5ea0: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
5eb0: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
5ec0: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
5ed0: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
5ee0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
5ef0: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
5f00: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
5f10: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
5f20: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
5f30: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
5f40: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
5f50: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
5f60: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
5f70: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
5f80: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
5f90: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
5fa0: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
5fb0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
5fc0: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
5fd0: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
5fe0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
5ff0: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
6000: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
6010: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
6020: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
6030: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
6040: 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f 56 45 52  n[] = SQLITE_VER
6050: 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f 41 50 49  SION;.SQLITE_API
6060: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
6070: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
6080: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
6090: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
60a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76  lite3_sourceid(v
60b0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
60c0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62   int sqlite3_lib
60d0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
60e0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
60f0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
6100: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
6110: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
6120: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
6130: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
6140: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
6150: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
6160: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
6170: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
6180: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
6190: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
61a0: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
61b0: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
61c0: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
61d0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
61e0: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
61f0: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
6200: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
6210: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
6220: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
6230: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
6240: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
6250: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
6260: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
6270: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
6280: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
6290: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
62a0: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
62b0: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
62c0: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
62d0: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
62e0: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
62f0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
6300: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
6310: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
6320: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
6330: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
6340: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
6350: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
6360: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
6370: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
6380: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
6390: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
63a0: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
63b0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
63c0: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
63d0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
63e0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
63f0: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
6400: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
6410: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
6420: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
6430: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
6440: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
6450: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
6460: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
6470: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
6480: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
6490: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
64a0: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
64b0: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
64c0: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
64d0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
64e0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
64f0: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
6500: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
6510: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
6520: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
6530: 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45  OptName);.SQLITE
6540: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
6550: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
6560: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
6570: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
6580: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
6590: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
65a0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
65b0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
65c0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
65d0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
65e0: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
65f0: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
6600: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
6610: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
6620: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
6630: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
6640: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
6650: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
6660: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
6670: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
6680: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
6690: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
66a0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
66b0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
66c0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
66d0: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
66e0: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
66f0: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
6700: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
6710: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
6720: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
6730: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
6740: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
6750: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
6760: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
6770: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
6780: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
6790: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
67a0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
67b0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
67c0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
67d0: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
67e0: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
67f0: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
6800: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
6810: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
6820: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
6830: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
6840: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
6850: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
6860: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
6870: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
6880: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
6890: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
68a0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
68b0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
68c0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
68d0: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
68e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
68f0: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
6900: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
6910: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
6920: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
6930: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
6940: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
6950: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
6960: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
6970: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
6980: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
6990: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
69a0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
69b0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
69c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
69d0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
69e0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
69f0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
6a00: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
6a10: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
6a20: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
6a30: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
6a40: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
6a50: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
6a60: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
6a70: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
6a80: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
6a90: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
6aa0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
6ab0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
6ac0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
6ad0: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
6ae0: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
6af0: 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20  _MUTEX].  ^(The 
6b00: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
6b10: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  the.** sqlite3_t
6b20: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
6b30: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20  tion shows only 
6b40: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
6b50: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74   setting of.** t
6b60: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f  hread safety, no
6b70: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
6b80: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73  hanges to that s
6b90: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a  etting made by.*
6ba0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  * sqlite3_config
6bb0: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  (). In other wor
6bc0: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ds, the return v
6bd0: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
6be0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a  3_threadsafe().*
6bf0: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62  * is unchanged b
6c00: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  y calls to sqlit
6c10: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a  e3_config().)^.*
6c20: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  *.** See the [th
6c30: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
6c40: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
6c50: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
6c60: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  mation..*/.SQLIT
6c70: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
6c80: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
6c90: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
6ca0: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
6cb0: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
6cc0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
6cd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
6ce0: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
6cf0: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
6d00: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
6d10: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
6d20: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
6d30: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
6d40: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
6d50: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
6d60: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
6d70: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
6d80: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
6d90: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
6da0: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
6db0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
6dc0: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
6dd0: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
6de0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
6df0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
6e00: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
6e10: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
6e20: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69  e3_close()].** i
6e30: 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  s its destructor
6e40: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e  .  There are man
6e50: 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63  y other interfac
6e60: 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b  es (such as.** [
6e70: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
6e80: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
6e90: 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
6ea0: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
6eb0: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
6ec0: 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20  ()] to name but 
6ed0: 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20  three) that are 
6ee0: 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a  methods on an.**
6ef0: 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e   sqlite3 object.
6f00: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
6f10: 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74  ct sqlite3 sqlit
6f20: 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e3;../*.** CAPI3
6f30: 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65  REF: 64-Bit Inte
6f40: 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59  ger Types.** KEY
6f50: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e  WORDS: sqlite_in
6f60: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  t64 sqlite_uint6
6f70: 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  4.**.** Because 
6f80: 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73  there is no cros
6f90: 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74  s-platform way t
6fa0: 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74  o specify 64-bit
6fb0: 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a   integer types.*
6fc0: 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65  * SQLite include
6fd0: 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36  s typedefs for 6
6fe0: 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64  4-bit signed and
6ff0: 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
7000: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  rs..**.** The sq
7010: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
7020: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
7030: 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
7040: 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e   type definition
7050: 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  s..** The sqlite
7060: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
7070: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61  e_uint64 types a
7080: 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72  re supported for
7090: 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f   backwards.** co
70a0: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79  mpatibility only
70b0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
70c0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
70d0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65  qlite_int64 type
70e0: 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65  s can store inte
70f0: 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  ger values.** be
7100: 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33  tween -922337203
7110: 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b  6854775808 and +
7120: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
7130: 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20  807 inclusive.  
7140: 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
7150: 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  uint64 and sqlit
7160: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63  e_uint64 types c
7170: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
7180: 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77   values .** betw
7190: 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36  een 0 and +18446
71a0: 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20  744073709551615 
71b0: 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69  inclusive..*/.#i
71c0: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
71d0: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
71e0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
71f0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
7200: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
7210: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
7220: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
7230: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
7240: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
7250: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
7260: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
7270: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
7280: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
7290: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
72a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
72b0: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
72c0: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
72d0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
72e0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
72f0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
7300: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
7310: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
7320: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
7330: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
7340: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
7350: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
7360: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
7370: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
7380: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
7390: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
73a0: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
73b0: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
73c0: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
73d0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
73e0: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
73f0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
7400: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
7410: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
7420: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
7430: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
7440: 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
7450: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
7460: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65  ) routine is the
7470: 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
7480: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
7490: 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20  ject..** ^Calls 
74a0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  to sqlite3_close
74b0: 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
74c0: 5f 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69  _OK if the [sqli
74d0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a  te3] object is.*
74e0: 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64  * successfully d
74f0: 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c  estroyed and all
7500: 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f   associated reso
7510: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
7520: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  cated..**.** App
7530: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b  lications must [
7540: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
7550: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
7560: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
7570: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ments].** and [s
7580: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
7590: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
75a0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73  BLOB handles] as
75b0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
75c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
75d0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
75e0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
75f0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
7600: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
7610: 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64  lose() is called
7620: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
7630: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
7640: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
7650: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
7660: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
7670: 6f 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  or [BLOB handles
7680: 5d 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ], then it retur
7690: 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53  ns.** SQLITE_BUS
76a0: 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71  Y..**.** ^If [sq
76b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69  lite3_close()] i
76c0: 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20  s invoked while 
76d0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
76e0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
76f0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
7700: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
7710: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
7720: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
7730: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
7740: 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68  C)] must be eith
7750: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
7760: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
7770: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
7780: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
7790: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
77a0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
77b0: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
77c0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
77d0: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
77e0: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
77f0: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
7800: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74  ite3_close() wit
7810: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
7820: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a   argument is a .
7830: 2a 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  ** harmless no-o
7840: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  p..*/.SQLITE_API
7850: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
7860: 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a  se(sqlite3 *);..
7870: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
7880: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
7890: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
78a0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
78b0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
78c0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
78d0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
78e0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
78f0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
7900: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
7910: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
7920: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
7930: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
7940: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7950: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
7960: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
7970: 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ce.**.** The sql
7980: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
7990: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
79a0: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
79b0: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
79c0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
79d0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
79e0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
79f0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
7a00: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
7a10: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
7a20: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
7a30: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
7a40: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
7a50: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
7a60: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
7a70: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
7a80: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
7a90: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
7aa0: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
7ab0: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
7ac0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
7ad0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
7ae0: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
7af0: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
7b00: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
7b10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
7b20: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
7b30: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
7b40: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
7b50: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
7b60: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
7b70: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
7b80: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
7b90: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
7ba0: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
7bb0: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
7bc0: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
7bd0: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
7be0: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
7bf0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
7c00: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
7c10: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
7c20: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
7c30: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
7c40: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
7c50: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
7c60: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
7c70: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
7c80: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
7c90: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
7ca0: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
7cb0: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
7cc0: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
7cd0: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
7ce0: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
7cf0: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
7d00: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
7d10: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
7d20: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
7d30: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
7d40: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
7d50: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
7d60: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
7d70: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
7d80: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
7d90: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
7da0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
7db0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
7dc0: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
7dd0: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
7de0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
7df0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
7e00: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
7e10: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
7e20: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
7e30: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
7e40: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
7e50: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
7e60: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
7e70: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
7e80: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
7e90: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
7ea0: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
7eb0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
7ec0: 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  r of.** of sqlit
7ed0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
7ee0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
7ef0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
7f00: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
7f10: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
7f20: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
7f30: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
7f40: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
7f50: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
7f60: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
7f70: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
7f80: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
7f90: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
7fa0: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
7fb0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
7fc0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
7fd0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
7fe0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
7ff0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
8000: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
8010: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
8020: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
8030: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
8040: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
8050: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
8060: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
8070: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
8080: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
8090: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
80a0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
80b0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
80c0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
80d0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
80e0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
80f0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
8100: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
8110: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
8120: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
8130: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
8140: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
8150: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
8160: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
8170: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
8180: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
8190: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
81a0: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
81b0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
81c0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
81d0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
81e0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
81f0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
8200: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
8210: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
8220: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
8230: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
8240: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
8250: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
8260: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
8270: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
8280: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
8290: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
82a0: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
82b0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
82c0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
82d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
82e0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
82f0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
8300: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
8310: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
8320: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
8330: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
8340: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
8350: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
8360: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
8370: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
8380: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
8390: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
83a0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
83b0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
83c0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
83d0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
83e0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
83f0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e  lication must in
8400: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
8410: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
8420: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
8430: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
8440: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
8450: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
8460: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
8470: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
8480: 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73  t close [databas
8490: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
84a0: 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
84b0: 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d     the 1st param
84c0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
84d0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
84e0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
84f0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20  unning..** <li> 
8500: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
8510: 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20  must not modify 
8520: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
8530: 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e  t text passed in
8540: 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32  to.**      the 2
8550: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
8560: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
8570: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
8580: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
8590: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ul>.*/.SQLI
85a0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
85b0: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
85c0: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
85d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
85e0: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
85f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
8600: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
8610: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8620: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
8630: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
8640: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
8650: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
8660: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
8670: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
8680: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
8690: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
86a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
86b0: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
86c0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
86d0: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
86e0: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
86f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8700: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
8710: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
8720: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8730: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  F: Result Codes.
8740: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
8750: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f  ITE_OK {error co
8760: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73  de} {error codes
8770: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
8780: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65  result code} {re
8790: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
87a0: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
87b0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
87c0: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
87d0: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
87e0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
87f0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
8800: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f  icates success o
8810: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
8820: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
8830: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8840: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
8850: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
8860: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
8870: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
8880: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
8890: 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c   codes],.** [sql
88a0: 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
88b0: 66 6c 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45  flict()] [SQLITE
88c0: 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75  _ROLLBACK | resu
88d0: 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64  lt codes]..*/.#d
88e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20  efine SQLITE_OK 
88f0: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
8900: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75   Successful resu
8910: 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69  lt */./* beginni
8920: 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  ng-of-error-code
8930: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
8940: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20  ITE_ERROR       
8950: 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f   1   /* SQL erro
8960: 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74  r or missing dat
8970: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
8980: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c   SQLITE_INTERNAL
8990: 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65       2   /* Inte
89a0: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72  rnal logic error
89b0: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64   in SQLite */.#d
89c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
89d0: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a  M         3   /*
89e0: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   Access permissi
89f0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
8a00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
8a10: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20  T        4   /* 
8a20: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  Callback routine
8a30: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62   requested an ab
8a40: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ort */.#define S
8a50: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20  QLITE_BUSY      
8a60: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61     5   /* The da
8a70: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c  tabase file is l
8a80: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
8a90: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20   SQLITE_LOCKED  
8aa0: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61       6   /* A ta
8ab0: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  ble in the datab
8ac0: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ase is locked */
8ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8ae0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20  NOMEM        7  
8af0: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66   /* A malloc() f
8b00: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ailed */.#define
8b10: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
8b20: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65       8   /* Atte
8b30: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
8b40: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
8b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8b60: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20  TE_INTERRUPT    
8b70: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  9   /* Operation
8b80: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73   terminated by s
8b90: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
8ba0: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ()*/.#define SQL
8bb0: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20  ITE_IOERR       
8bc0: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e  10   /* Some kin
8bd0: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72  d of disk I/O er
8be0: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a  ror occurred */.
8bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
8c00: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20  ORRUPT     11   
8c10: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
8c20: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61  disk image is ma
8c30: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69  lformed */.#defi
8c40: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  ne SQLITE_NOTFOU
8c50: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e  ND    12   /* Un
8c60: 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20  known opcode in 
8c70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8c80: 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e  trol() */.#defin
8c90: 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20  e SQLITE_FULL   
8ca0: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73       13   /* Ins
8cb0: 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65  ertion failed be
8cc0: 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69  cause database i
8cd0: 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e  s full */.#defin
8ce0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
8cf0: 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61  N    14   /* Una
8d00: 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ble to open the 
8d10: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
8d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8d30: 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20  PROTOCOL    15  
8d40: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63   /* Database loc
8d50: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
8d60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8d70: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
8d80: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
8d90: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
8da0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
8db0: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
8dc0: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
8dd0: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
8de0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
8df0: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
8e00: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
8e10: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
8e20: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
8e30: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
8e40: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
8e50: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
8e60: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
8e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
8e80: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
8e90: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
8ea0: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
8eb0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
8ec0: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
8ed0: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
8ee0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
8ef0: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
8f00: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
8f10: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
8f20: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
8f30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8f40: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
8f50: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
8f60: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
8f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
8f80: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
8f90: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
8fa0: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
8fb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8fc0: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
8fd0: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
8fe0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
8ff0: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
9000: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
9010: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
9020: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
9030: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
9040: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
9050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9060: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
9070: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
9080: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
9090: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
90a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
90b0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
90c0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
90d0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
90e0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
90f0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
9100: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
9110: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
9120: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
9130: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
9140: 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78   error code} {ex
9150: 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
9160: 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
9170: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
9180: 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65  t code} {extende
9190: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a  d result codes}.
91a0: 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66  **.** In its def
91b0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
91c0: 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72  on, SQLite API r
91d0: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f  outines return o
91e0: 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72  ne of 26 integer
91f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c  .** [SQLITE_OK |
9200: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20   result codes]. 
9210: 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69   However, experi
9220: 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74  ence has shown t
9230: 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74  hat many of.** t
9240: 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65  hese result code
9250: 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65  s are too coarse
9260: 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20  -grained.  They 
9270: 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  do not provide a
9280: 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d  s.** much inform
9290: 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62  ation about prob
92a0: 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d  lems as programm
92b0: 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20  ers might like. 
92c0: 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f   In an effort to
92d0: 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73  .** address this
92e0: 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  , newer versions
92f0: 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73   of SQLite (vers
9300: 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61  ion 3.3.8 and la
9310: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
9320: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
9330: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
9340: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
9350: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
9360: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
9370: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20  out errors. The 
9380: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
9390: 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65  codes are enable
93a0: 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
93b0: 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61   on a per databa
93c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  se connection ba
93d0: 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  sis using the.**
93e0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
93f0: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
9400: 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f  )] API..**.** So
9410: 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61  me of the availa
9420: 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  ble extended res
9430: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69  ult codes are li
9440: 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e  sted here..** On
9450: 65 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65  e may expect the
9460: 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e   number of exten
9470: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
9480: 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a   will be expand.
9490: 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53  ** over time.  S
94a0: 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65  oftware that use
94b0: 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  s extended resul
94c0: 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65  t codes should e
94d0: 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20  xpect.** to see 
94e0: 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73  new result codes
94f0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
9500: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
9510: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
9520: 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77  OK result code w
9530: 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74  ill never be ext
9540: 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20  ended.  It will 
9550: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61  always.** be exa
9560: 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64  ctly zero..*/.#d
9570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9580: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
9590: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
95a0: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
95b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
95c0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
95d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
95e0: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
95f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
9600: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
9610: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
9620: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
9630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
9640: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
9650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
9660: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
9670: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
9680: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
9690: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
96a0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
96b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
96c0: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
96d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
96e0: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
96f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
9700: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
9710: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9720: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
9730: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
9740: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
9750: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
9760: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9770: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
9780: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
9790: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
97a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
97b0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
97c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
97d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
97e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
97f0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
9800: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
9810: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
9820: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9830: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
9840: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9850: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
9860: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9870: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53  ITE_IOERR_ACCESS
9880: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9890: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c  ITE_IOERR | (13<
98a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
98b0: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52  ITE_IOERR_CHECKR
98c0: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
98d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
98e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
98f0: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
9900: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9910: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
9920: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9930: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
9940: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9950: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c  ITE_IOERR | (16<
9960: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9970: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
9980: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
9990: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
99a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
99b0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
99c0: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
99d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
99e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
99f0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a  ITE_IOERR_SHMSIZ
9a00: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
9a10: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
9a20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9a30: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43  ITE_IOERR_SHMLOC
9a40: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
9a50: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
9a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9a70: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50  ITE_IOERR_SHMMAP
9a80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9a90: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c  ITE_IOERR | (21<
9aa0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9ab0: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20  ITE_IOERR_SEEK  
9ac0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9ad0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c  ITE_IOERR | (22<
9ae0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9af0: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
9b00: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
9b10: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
9b20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9b30: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
9b40: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
9b50: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
9b60: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
9b70: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e  QLITE_CANTOPEN_N
9b80: 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53  OTEMPDIR      (S
9b90: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
9ba0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
9bb0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
9bc0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
9bd0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
9be0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
9bf0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
9c00: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
9c10: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
9c20: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
9c30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
9c40: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
9c50: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
9c60: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f  NLY | (2<<8))../
9c70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
9c80: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
9c90: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
9ca0: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
9cb0: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
9cc0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
9cd0: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
9ce0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
9cf0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
9d00: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
9d10: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
9d20: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
9d30: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
9d40: 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  thod..*/.#define
9d50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
9d60: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
9d70: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
9d80: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9d90: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9da0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
9db0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
9dc0: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
9dd0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9de0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9df0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9e00: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
9e10: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
9e20: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9e30: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9e40: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
9e50: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
9e60: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
9e70: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9e80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
9e90: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
9ea0: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
9eb0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9ec0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
9ed0: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
9ee0: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
9ef0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9f00: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
9f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
9f20: 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20  00000040  /* Ok 
9f30: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9f40: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9f50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
9f60: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
9f70: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
9f80: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9f90: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
9fa0: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
9fb0: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
9fc0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9fd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
9fe0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
9ff0: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
a000: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a010: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
a020: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
a030: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
a040: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a050: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
a060: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
a070: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
a080: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a090: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
a0a0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
a0b0: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
a0c0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a0d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
a0e0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
a0f0: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
a100: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a110: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
a120: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
a130: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
a140: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a150: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a160: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
a170: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
a180: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
a190: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a1a0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a1b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
a1c0: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
a1d0: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
a1e0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a1f0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a200: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
a210: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
a220: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
a230: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a240: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a250: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
a260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
a270: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
a280: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
a290: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
a2a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
a2b0: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
a2c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
a2d0: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
a2e0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
a2f0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a300: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
a310: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
a320: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
a330: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
a340: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
a350: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
a360: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
a370: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
a380: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
a390: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
a3a0: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
a3b0: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
a3c0: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
a3d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
a3e0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
a3f0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
a400: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
a410: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
a420: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
a430: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
a440: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
a450: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a460: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
a470: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
a480: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
a490: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
a4a0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
a4b0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
a4c0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
a4d0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
a4e0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
a4f0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
a500: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
a510: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
a520: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
a530: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
a540: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
a550: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
a560: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
a570: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
a580: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
a590: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
a5a0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
a5b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
a5c0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
a5d0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
a5e0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
a5f0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
a600: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
a610: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
a620: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
a630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
a640: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
a650: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
a660: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
a670: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
a680: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
a690: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
a6a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
a6b0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
a6c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
a6d0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
a6e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a6f0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
a700: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
a710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
a720: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
a730: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a740: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
a750: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
a760: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
a770: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
a780: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
a790: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
a7a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
a7b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a7c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
a7d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
a7e0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
a7f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a800: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
a810: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
a820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
a830: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
a840: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
a850: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
a860: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
a870: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
a880: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
a890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
a8a0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
a8b0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
a8c0: 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
a8d0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
a8e0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
a8f0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
a900: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
a910: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
a920: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
a930: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
a940: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
a950: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
a960: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
a970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a980: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
a990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a9a0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
a9b0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
a9c0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
a9d0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
a9e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
a9f0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
aa00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
aa10: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
aa20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
aa30: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
aa40: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
aa50: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
aa60: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
aa70: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
aa80: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
aa90: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
aaa0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
aab0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
aac0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
aad0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
aae0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
aaf0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
ab00: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
ab10: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
ab20: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
ab30: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
ab40: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
ab50: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
ab60: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
ab70: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
ab80: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
ab90: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
aba0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
abb0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
abc0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
abd0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
abe0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
abf0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
ac00: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
ac10: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
ac20: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
ac30: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
ac40: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
ac50: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
ac60: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
ac70: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
ac80: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
ac90: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
aca0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
acb0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
acc0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
acd0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
ace0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
acf0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
ad00: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
ad10: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
ad20: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
ad30: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
ad40: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
ad50: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
ad60: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
ad70: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
ad80: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
ad90: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
ada0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
adb0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
adc0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
add0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
ade0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
adf0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
ae00: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
ae10: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
ae20: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
ae30: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
ae40: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
ae50: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
ae60: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
ae70: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
ae80: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
ae90: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
aea0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
aeb0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
aec0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
aed0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
aee0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
aef0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
af00: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
af10: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
af20: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
af30: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
af40: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
af50: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
af60: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
af70: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
af80: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
af90: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
afa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
afb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
afc0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
afd0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
afe0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
aff0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
b000: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
b010: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
b020: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
b030: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
b040: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
b050: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
b060: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
b070: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
b080: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
b090: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
b0a0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
b0b0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
b0c0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
b0d0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
b0e0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
b0f0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
b100: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
b110: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
b120: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
b130: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
b140: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
b150: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
b160: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
b170: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
b180: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
b190: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
b1a0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
b1b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
b1c0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
b1d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
b1e0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
b1f0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
b200: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
b210: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
b220: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
b230: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
b240: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
b250: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
b260: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
b270: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
b280: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
b290: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
b2a0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
b2b0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
b2c0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
b2d0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
b2e0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
b2f0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
b300: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
b310: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
b320: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
b330: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
b340: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
b350: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
b360: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
b370: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
b380: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
b390: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
b3a0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
b3b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
b3c0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
b3d0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
b3e0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
b3f0: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
b400: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
b410: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
b420: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
b430: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
b440: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
b450: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
b460: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
b470: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
b480: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
b490: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
b4a0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
b4b0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
b4c0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
b4d0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
b4e0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
b4f0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
b500: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
b510: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
b520: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
b530: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
b540: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
b550: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
b560: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
b570: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
b580: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
b590: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
b5a0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
b5b0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
b5c0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
b5d0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
b5e0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
b5f0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
b600: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
b610: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
b620: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
b630: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
b640: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
b650: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
b660: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
b670: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
b680: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
b690: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
b6a0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
b6b0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
b6c0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
b6d0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
b6e0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
b6f0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
b700: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
b710: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
b720: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
b730: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
b740: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
b750: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
b760: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
b770: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
b780: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
b790: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
b7a0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
b7b0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
b7c0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
b7d0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
b7e0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
b7f0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
b800: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
b810: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
b820: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
b830: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
b840: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
b850: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
b860: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
b870: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
b880: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
b890: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
b8a0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
b8b0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
b8c0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
b8d0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
b8e0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
b8f0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
b900: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
b910: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
b920: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
b930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
b940: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
b950: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
b960: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
b970: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
b980: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
b990: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
b9a0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
b9b0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
b9c0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
b9d0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
b9e0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
b9f0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
ba00: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
ba10: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
ba20: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
ba30: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
ba40: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
ba50: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
ba60: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
ba70: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
ba80: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
ba90: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
baa0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
bab0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
bac0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
bad0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
bae0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
baf0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
bb00: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
bb10: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
bb20: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
bb30: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
bb40: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
bb50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
bb60: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
bb70: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
bb80: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
bb90: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
bba0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
bbb0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
bbc0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
bbd0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
bbe0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
bbf0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
bc00: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
bc10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
bc20: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
bc30: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
bc40: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
bc50: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
bc60: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
bc70: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
bc80: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
bc90: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
bca0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
bcb0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
bcc0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
bcd0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
bce0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
bcf0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
bd00: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
bd10: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
bd20: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
bd30: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
bd40: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
bd50: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
bd60: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
bd70: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
bd80: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
bd90: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
bda0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
bdb0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
bdc0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
bdd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
bde0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
bdf0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
be00: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
be20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
be40: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
be60: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
be80: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be90: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
bea0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
beb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
bec0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
bed0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
bee0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
bef0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
bf00: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
bf10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
bf20: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
bf30: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
bf40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
bf50: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
bf60: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
bf70: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
bf80: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
bf90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
bfa0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
bfb0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
bfc0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
bfd0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
bfe0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
bff0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
c000: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
c010: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
c020: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
c030: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
c040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
c050: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
c060: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
c070: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
c080: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
c090: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
c0a0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
c0b0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
c0c0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
c0d0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
c0e0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
c0f0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
c100: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
c110: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
c120: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
c130: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
c140: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
c150: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
c160: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
c170: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
c180: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
c190: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
c1a0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
c1b0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
c1c0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
c1d0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
c1e0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
c1f0: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
c200: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
c210: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
c220: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
c230: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
c240: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
c250: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
c260: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
c270: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
c280: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
c290: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c2a0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
c2b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
c2c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
c2d0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
c2e0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
c2f0: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
c300: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
c310: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
c320: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
c330: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
c340: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
c350: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
c360: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
c370: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
c380: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
c390: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
c3a0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
c3b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
c3c0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
c3d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
c3e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
c3f0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
c400: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
c410: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
c420: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
c430: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
c440: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
c450: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
c460: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
c470: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
c480: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
c490: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
c4a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
c4b0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
c4c0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
c4d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
c4e0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
c4f0: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
c500: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
c510: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
c520: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
c530: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
c540: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
c550: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
c560: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
c570: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
c580: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
c590: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
c5a0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
c5b0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
c5c0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
c5d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
c5e0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
c5f0: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
c600: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
c610: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
c620: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
c630: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
c640: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
c650: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
c660: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
c670: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
c680: 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 2 */.  /* Add
c690: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
c6a0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
c6b0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
c6c0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
c6d0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
c6e0: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
c6f0: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
c700: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
c710: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
c720: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
c730: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
c740: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
c750: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
c760: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
c770: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
c780: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
c790: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
c7a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
c7b0: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
c7c0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
c7d0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
c7e0: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
c7f0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
c800: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
c810: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
c820: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
c830: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
c840: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
c850: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
c860: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
c870: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
c880: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
c890: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
c8a0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
c8b0: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
c8c0: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
c8d0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
c8e0: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
c8f0: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
c900: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
c910: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
c920: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
c930: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
c940: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
c950: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c960: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
c970: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
c980: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
c990: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
c9a0: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
c9b0: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
c9c0: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
c9d0: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
c9e0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
c9f0: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
ca00: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
ca10: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
ca20: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
ca30: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
ca40: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
ca50: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
ca60: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
ca70: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
ca80: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
ca90: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
caa0: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
cab0: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
cac0: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
cad0: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ster..**.** The 
cae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
caf0: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
cb00: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
cb10: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
cb20: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
cb30: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
cb40: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
cb50: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
cb60: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
cb70: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
cb80: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
cb90: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
cba0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
cbb0: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
cbc0: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
cbd0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
cbe0: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
cbf0: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
cc00: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
cc10: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
cc20: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
cc30: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
cc40: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
cc50: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
cc60: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
cc70: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
cc80: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
cc90: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
cca0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
ccb0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
ccc0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
ccd0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
cce0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
ccf0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
cd00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
cd10: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
cd20: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
cd30: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
cd40: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
cd50: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
cd60: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
cd70: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
cd80: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
cd90: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
cda0: 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45  ** ^(The [SQLITE
cdb0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
cdc0: 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TED] opcode is g
cdd0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
cde0: 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65  lly by.** SQLite
cdf0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c   and sent to all
ce00: 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65 20   VFSes in place 
ce10: 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 65  of a call to the
ce20: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a   xSync method.**
ce30: 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
ce40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  se connection ha
ce50: 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  s [PRAGMA synchr
ce60: 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f 46  onous] set to OF
ce70: 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65  F.)^.** Some spe
ce80: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 6e  cialized VFSes n
ce90: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
cea0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 72  in order to oper
ceb0: 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a  ate correctly.**
cec0: 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 79   when [PRAGMA sy
ced0: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
cee0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
cef0: 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74 20  FF] is set, but 
cf00: 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 64  most .** VFSes d
cf10: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
cf20: 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c  signal and shoul
cf30: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
cf40: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  e this opcode..*
cf50: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
cf60: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
cf70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
cf80: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
cf90: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 64  s.** opcode as d
cfa0: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
cfb0: 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  upt the operatio
cfc0: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
cfd0: 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 68  ized VFSes.** th
cfe0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
cff0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  .  .**.** ^The [
d000: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
d010: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
d020: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
d030: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
d040: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
d050: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
d060: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
d070: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
d080: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
d090: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
d0a0: 65 72 20 74 6f 20 77 6f 72 6b 20 74 6f 20 70 72  er to work to pr
d0b0: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
d0c0: 20 61 67 61 69 6e 73 74 0a 2a 2a 20 61 6e 74 69   against.** anti
d0d0: 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e  -virus programs.
d0e0: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
d0f0: 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69  e windows VFS wi
d100: 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65  ll retry file re
d110: 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74  ad,.** file writ
d120: 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65  e, and file dele
d130: 74 65 20 6f 70 65 72 74 69 6f 6e 73 20 75 70 20  te opertions up 
d140: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
d150: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
d160: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
d170: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
d180: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
d190: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
d1a0: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
d1b0: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
d1c0: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
d1d0: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
d1e0: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
d1f0: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 6f 73  code allows thos
d200: 65 20 74 6f 20 76 61 6c 75 65 73 20 28 31 30 20  e to values (10 
d210: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
d220: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
d230: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
d240: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
d250: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
d260: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
d270: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
d280: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
d290: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
d2a0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
d2b0: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
d2c0: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
d2d0: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
d2e0: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
d2f0: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
d300: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
d310: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
d320: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
d330: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
d340: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
d350: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
d360: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
d370: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
d380: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
d390: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
d3a0: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
d3b0: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
d3c0: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
d3d0: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
d3e0: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
d3f0: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
d400: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
d410: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
d420: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
d430: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
d440: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
d450: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
d460: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
d470: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41  t [WAL | Write A
d480: 48 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e  Head Log] settin
d490: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  g.  By default, 
d4a0: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a  the auxiliary.**
d4b0: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67   write ahead log
d4c0: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
d4d0: 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f  ry files used fo
d4e0: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  r transaction co
d4f0: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74  ntrol.** are aut
d500: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
d510: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65  ed when the late
d520: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  st connection to
d530: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
d540: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e   closes.  Settin
d550: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  g persistent WAL
d560: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f   mode causes tho
d570: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73  se files to pers
d580: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f  ist after.** clo
d590: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20  se.  Persisting 
d5a0: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65  the files is use
d5b0: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70  ful when other p
d5c0: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f  rocesses that do
d5d0: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69   not.** have wri
d5e0: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e  te permission on
d5f0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63   the directory c
d600: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
d610: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74  tabase file want
d620: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20  .** to read the 
d630: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61  database file, a
d640: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68  s the WAL and sh
d650: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
d660: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20  s must exist.** 
d670: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65  in order for the
d680: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   database to be 
d690: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
d6a0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
d6b0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
d6c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
d6d0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
d6e0: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
d6f0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
d700: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
d710: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
d720: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  e persistent WAL
d730: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
d740: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a  able persistent.
d750: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66  ** WAL mode.  If
d760: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
d770: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
d780: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
d790: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57  the current.** W
d7a0: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73  AL persistence s
d7b0: 65 74 74 69 6e 67 2e 0a 2a 2a 20 0a 2a 2f 0a 23  etting..** .*/.#
d7c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d7d0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
d7e0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
d7f0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
d800: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23  OXYFILE      2.#
d810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
d820: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
d830: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
d840: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
d850: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
d860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d870: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
d880: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
d890: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
d8a0: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 36 0a 23  K_SIZE       6.#
d8b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d8c0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
d8d0: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
d8e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
d8f0: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 38 0a 23  _OMITTED     8.#
d900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d910: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
d920: 52 59 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53  RY   9.#define S
d930: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
d940: 49 53 54 5f 57 41 4c 20 20 20 20 20 31 30 0a 0a  IST_WAL     10..
d950: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d960: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
d970: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
d980: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
d990: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
d9a0: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
d9b0: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
d9c0: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
d9d0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
d9e0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
d9f0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
da00: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
da10: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
da20: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
da30: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
da40: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
da50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
da60: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
da70: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
da80: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
da90: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
daa0: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
dab0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
dac0: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
dad0: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
dae0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
daf0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
db00: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
db10: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
db20: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
db30: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
db40: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
db50: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
db60: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
db70: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
db80: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
db90: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
dba0: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
dbb0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
dbc0: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
dbd0: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
dbe0: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
dbf0: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
dc00: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
dc10: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
dc20: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
dc30: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
dc40: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
dc50: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
dc60: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
dc70: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
dc80: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
dc90: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
dca0: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
dcb0: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
dcc0: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
dcd0: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
dce0: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
dcf0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
dd00: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
dd10: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
dd20: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
dd30: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
dd40: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
dd50: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
dd60: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
dd70: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
dd80: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
dd90: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
dda0: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
ddb0: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
ddc0: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
ddd0: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
dde0: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
ddf0: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
de00: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
de10: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
de20: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
de30: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
de40: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
de50: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
de60: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
de70: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
de80: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
de90: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
dea0: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
deb0: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
dec0: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
ded0: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
dee0: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
def0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
df00: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
df10: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
df20: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
df30: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
df40: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
df50: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
df60: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
df70: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
df80: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
df90: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
dfa0: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
dfb0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
dfc0: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
dfd0: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
dfe0: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
dff0: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
e000: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
e010: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
e020: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
e030: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
e040: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
e050: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
e060: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
e070: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
e080: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
e090: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
e0a0: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
e0b0: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
e0c0: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
e0d0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
e0e0: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
e0f0: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
e100: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
e110: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
e120: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
e130: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
e140: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
e150: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
e160: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e170: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
e180: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
e190: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
e1a0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
e1b0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
e1c0: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
e1d0: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
e1e0: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
e1f0: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
e200: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
e210: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
e220: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
e230: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
e240: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
e250: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30   more than.** 10
e260: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
e270: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
e280: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
e290: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
e2a0: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
e2b0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
e2c0: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
e2d0: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
e2e0: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
e2f0: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
e300: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
e310: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
e320: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
e330: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
e340: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
e350: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
e360: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
e370: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
e380: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
e390: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
e3a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
e3b0: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
e3c0: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
e3d0: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
e3e0: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
e3f0: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
e400: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
e410: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
e420: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
e430: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
e440: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
e450: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
e460: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
e470: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
e480: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
e490: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
e4a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
e4b0: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
e4c0: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
e4d0: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
e4e0: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
e4f0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
e500: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
e510: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
e520: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
e530: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
e540: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
e550: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
e560: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
e570: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
e580: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
e590: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
e5a0: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
e5b0: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
e5c0: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
e5d0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
e5e0: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
e5f0: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
e600: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
e610: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
e620: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
e630: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
e640: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
e650: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
e660: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
e670: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
e680: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
e690: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e6a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
e6b0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e6c0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
e6d0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
e6e0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
e6f0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
e700: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
e710: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
e720: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
e730: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
e740: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e750: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
e760: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e770: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
e780: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
e790: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
e7a0: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
e7b0: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
e7c0: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
e7d0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
e7e0: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
e7f0: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
e800: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
e810: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
e820: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
e830: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
e840: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
e850: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
e860: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
e870: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
e880: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
e890: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
e8a0: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
e8b0: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
e8c0: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
e8d0: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
e8e0: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
e8f0: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
e900: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
e910: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
e920: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
e930: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
e940: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
e950: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
e960: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
e970: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
e980: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
e990: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
e9a0: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
e9b0: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
e9c0: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
e9d0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
e9e0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
e9f0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
ea00: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
ea10: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
ea20: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
ea30: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
ea40: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
ea50: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
ea60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
ea70: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
ea80: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
ea90: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
eaa0: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
eab0: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
eac0: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
ead0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
eae0: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
eaf0: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
eb00: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
eb10: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
eb20: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
eb30: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
eb40: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
eb50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
eb60: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
eb70: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
eb80: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
eb90: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
eba0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
ebb0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
ebc0: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
ebd0: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
ebe0: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
ebf0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
ec00: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
ec10: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
ec20: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
ec30: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
ec40: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
ec50: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
ec60: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
ec70: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
ec80: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
ec90: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
eca0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
ecb0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
ecc0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
ecd0: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
ece0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
ecf0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
ed00: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
ed10: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
ed20: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
ed30: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
ed40: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
ed50: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
ed60: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
ed70: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
ed80: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
ed90: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
eda0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
edb0: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
edc0: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
edd0: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
ede0: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
edf0: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
ee00: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
ee10: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
ee20: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
ee30: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
ee40: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
ee50: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
ee60: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
ee70: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
ee80: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
ee90: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
eea0: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
eeb0: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
eec0: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
eed0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
eee0: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
eef0: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
ef00: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
ef10: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
ef20: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
ef30: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
ef40: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
ef50: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
ef60: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
ef70: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
ef80: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
ef90: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
efa0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
efb0: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
efc0: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
efd0: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
efe0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
eff0: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
f000: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
f010: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
f020: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
f030: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
f040: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
f050: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
f060: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
f070: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
f080: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
f090: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
f0a0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
f0b0: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
f0c0: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
f0d0: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
f0e0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
f0f0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
f100: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
f110: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
f120: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
f130: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
f140: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
f150: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
f160: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
f170: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
f180: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
f190: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
f1a0: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
f1b0: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
f1c0: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
f1d0: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
f1e0: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
f1f0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
f200: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
f210: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
f220: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
f230: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
f240: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
f250: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
f260: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
f270: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
f280: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
f290: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
f2a0: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
f2b0: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
f2c0: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
f2d0: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
f2e0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
f2f0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
f300: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
f310: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
f320: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
f330: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
f340: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
f350: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
f360: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
f370: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
f380: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
f390: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
f3a0: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
f3b0: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
f3c0: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
f3d0: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
f3e0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
f3f0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
f400: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
f410: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
f420: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
f430: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
f440: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
f450: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
f460: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
f470: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
f480: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
f490: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
f4a0: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
f4b0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
f4c0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
f4d0: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
f4e0: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
f4f0: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
f500: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
f510: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
f520: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
f530: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
f540: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
f550: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
f560: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
f570: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
f580: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
f590: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
f5a0: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
f5b0: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
f5c0: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
f5d0: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
f5e0: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
f5f0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
f600: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
f610: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
f620: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
f630: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
f640: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
f650: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
f660: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
f670: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
f680: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
f690: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
f6a0: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
f6b0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
f6c0: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
f6d0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
f6e0: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
f6f0: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
f700: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
f710: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
f720: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
f730: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
f740: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
f750: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
f760: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
f770: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
f780: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
f790: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
f7a0: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
f7b0: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
f7c0: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
f7d0: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
f7e0: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
f7f0: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
f800: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
f810: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
f820: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
f830: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
f840: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
f850: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
f860: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
f870: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
f880: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
f890: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
f8a0: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
f8b0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
f8c0: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
f8d0: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
f8e0: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
f8f0: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
f900: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
f910: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
f920: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
f930: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
f940: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
f950: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
f960: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
f970: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
f980: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
f990: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
f9a0: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
f9b0: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
f9c0: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
f9d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
f9e0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
f9f0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
fa00: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
fa10: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
fa20: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
fa30: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
fa40: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
fa50: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
fa60: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
fa70: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
fa80: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
fa90: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
faa0: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
fab0: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
fac0: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
fad0: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
fae0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
faf0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
fb00: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
fb10: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
fb20: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
fb30: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
fb40: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
fb50: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
fb60: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
fb70: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
fb80: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
fb90: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
fba0: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
fbb0: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
fbc0: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
fbd0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
fbe0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
fbf0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
fc00: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
fc10: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
fc20: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
fc30: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
fc40: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
fc50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
fc60: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
fc70: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
fc80: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
fc90: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
fca0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
fcb0: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
fcc0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
fcd0: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
fce0: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
fcf0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
fd00: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
fd10: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
fd20: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
fd30: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
fd40: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
fd50: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
fd60: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
fd70: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
fd80: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
fd90: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
fda0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
fdb0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
fdc0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
fdd0: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
fde0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
fdf0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
fe00: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
fe10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
fe20: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
fe30: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
fe40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
fe50: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
fe60: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
fe70: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
fe80: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
fe90: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
fea0: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
feb0: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
fec0: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
fed0: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
fee0: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
fef0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
ff00: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
ff10: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
ff20: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
ff30: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
ff40: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
ff50: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
ff60: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
ff70: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
ff80: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
ff90: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
ffa0: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
ffb0: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
ffc0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ffd0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ffe0: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
fff0: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
10000 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
10010 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
10020 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10030 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
10040 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
10050 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
10060 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10070 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
10080 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
10090 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
100a0 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
100b0 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
100c0 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
100d0 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
100e0 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
100f0 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
10100 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
10110 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
10120 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
10130 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
10140 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
10150 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10160 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
10170 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
10180 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
10190 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
101a0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
101b0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
101c0 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
101d0 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
101e0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
101f0 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
10200 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
10210 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
10220 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
10230 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
10240 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
10250 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
10260 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
10270 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
10280 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
10290 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
102a0 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
102b0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
102c0 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
102d0 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
102e0 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
102f0 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
10300 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
10310 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
10320 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
10330 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
10340 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
10350 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
10360 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
10370 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
10380 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
10390 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
103a0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
103b0 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
103c0 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
103d0 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
103e0 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
103f0 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
10400 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
10410 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
10420 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10430 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
10440 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
10450 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
10460 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
10470 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
10480 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
10490 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
104a0 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
104b0 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
104c0 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
104d0 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
104e0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
104f0 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
10500 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
10510 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
10520 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
10530 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
10540 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
10550 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
10560 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10570 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
10580 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
10590 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
105a0 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
105b0 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
105c0 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
105d0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
105e0 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
105f0 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
10600 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
10610 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
10620 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
10630 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
10640 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
10650 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
10660 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
10670 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
10680 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
10690 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
106a0 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
106b0 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
106c0 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
106d0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
106e0 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
106f0 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
10700 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
10710 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
10720 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
10730 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
10740 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
10750 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
10760 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
10770 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
10780 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
10790 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
107a0 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
107b0 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65  was given no the
107c0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
107d0 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
107e0 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
107f0 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
10800 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
10810 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
10820 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
10830 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
10840 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
10850 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
10860 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
10870 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
10880 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
10890 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
108a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
108b0 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
108c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
108d0 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
108e0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
108f0 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
10900 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
10910 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
10920 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
10930 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
10940 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
10950 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
10960 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
10970 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
10980 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
10990 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
109a0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
109b0 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
109c0 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
109d0 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
109e0 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
109f0 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
10a00 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
10a10 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
10a20 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
10a30 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
10a40 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
10a50 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
10a60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
10a70 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
10a80 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
10a90 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
10aa0 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
10ab0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
10ac0 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
10ad0 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
10ae0 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
10af0 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
10b00 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
10b10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
10b20 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
10b30 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
10b40 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
10b50 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
10b60 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
10b70 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
10b80 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
10b90 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
10ba0 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
10bb0 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
10bc0 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
10bd0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
10be0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
10bf0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
10c00 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
10c10 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
10c20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
10c30 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10c40 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
10c50 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
10c60 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
10c70 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
10c80 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
10c90 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10ca0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
10cb0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
10cc0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
10cd0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
10ce0 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
10cf0 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
10d00 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10d10 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
10d20 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
10d30 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
10d40 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
10d50 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
10d60 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
10d70 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
10d80 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
10d90 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
10da0 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
10db0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
10dc0 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
10dd0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10de0 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
10df0 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
10e00 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
10e10 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
10e20 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
10e30 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
10e40 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
10e50 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10e60 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
10e70 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
10e80 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
10e90 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
10ea0 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
10eb0 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
10ec0 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
10ed0 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
10ee0 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
10ef0 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
10f00 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
10f10 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
10f20 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
10f30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10f40 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
10f50 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
10f60 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
10f70 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
10f80 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
10f90 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
10fa0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
10fb0 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
10fc0 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
10fd0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10fe0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
10ff0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11000 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
11010 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11020 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
11030 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
11040 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
11050 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11060 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
11070 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
11080 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
11090 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
110a0 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
110b0 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
110c0 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
110d0 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
110e0 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
110f0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
11100 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
11110 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
11120 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
11130 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
11140 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
11150 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
11160 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
11170 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
11180 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
11190 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
111a0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
111b0 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
111c0 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
111d0 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
111e0 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
111f0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
11200 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
11210 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
11220 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
11230 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
11240 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11250 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
11260 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
11270 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
11280 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
11290 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
112a0 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
112b0 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
112c0 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
112d0 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
112e0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
112f0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
11300 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
11310 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
11320 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
11330 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
11340 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
11350 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
11360 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
11370 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
11380 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
11390 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
113a0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
113b0 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
113c0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
113d0 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
113e0 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
113f0 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
11400 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
11410 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
11420 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
11430 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
11440 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
11450 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
11460 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11470 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
11480 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
11490 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
114a0 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
114b0 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
114c0 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
114d0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
114e0 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
114f0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
11500 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
11510 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
11520 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
11530 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
11540 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
11550 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
11560 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
11570 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
11580 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
11590 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
115a0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
115b0 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
115c0 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
115d0 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
115e0 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
115f0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
11600 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
11610 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
11620 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
11630 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
11640 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
11650 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
11660 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
11670 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
11680 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
11690 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
116a0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
116b0 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
116c0 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
116d0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
116e0 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
116f0 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
11700 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
11710 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
11720 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
11730 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
11740 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
11750 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
11760 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
11770 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
11780 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
11790 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
117a0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
117b0 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
117c0 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
117d0 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
117e0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
117f0 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
11800 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
11810 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
11820 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
11830 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
11840 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
11850 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
11860 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
11870 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
11880 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
11890 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
118a0 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
118b0 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
118c0 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
118d0 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
118e0 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
118f0 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
11900 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
11910 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
11920 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
11930 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
11940 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
11950 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
11960 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
11970 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
11980 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11990 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
119a0 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
119b0 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
119c0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
119d0 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
119e0 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
119f0 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
11a00 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
11a10 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
11a20 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
11a30 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
11a40 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
11a50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
11a60 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11a70 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ize(void);.SQLIT
11a80 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
11a90 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
11aa0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
11ab0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11ac0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
11ad0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
11ae0 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
11af0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11b00 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
11b10 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
11b20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
11b30 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
11b40 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
11b50 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
11b60 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
11b70 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
11b80 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
11b90 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
11ba0 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
11bb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
11bc0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
11bd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
11be0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
11bf0 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
11c00 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
11c10 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
11c20 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
11c30 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
11c40 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
11c50 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
11c60 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
11c70 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eeds..**.** The 
11c80 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11c90 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
11ca0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  t threadsafe.  T
11cb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
11cc0 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  * must insure th
11cd0 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
11ce0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
11cf0 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
11d00 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
11d10 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
11d20 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
11d30 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73    Furthermore, s
11d40 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a  qlite3_config().
11d50 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
11d60 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
11d70 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
11d80 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
11d90 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
11da0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
11db0 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
11dc0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11dd0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
11de0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
11df0 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
11e00 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
11e10 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
11e20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11e30 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
11e40 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
11e50 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
11e60 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
11e70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11e80 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
11e90 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
11ea0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
11eb0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
11ec0 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
11ed0 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
11ee0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
11ef0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
11f00 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
11f10 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
11f20 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11f30 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
11f40 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
11f50 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
11f60 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
11f70 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
11f80 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
11f90 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
11fa0 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
11fb0 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
11fc0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11fd0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
11fe0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11ff0 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
12000 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
12010 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
12020 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
12030 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
12040 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
12050 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
12060 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
12070 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
12080 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
12090 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
120a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
120b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
120c0 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
120d0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
120e0 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
120f0 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
12100 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
12110 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
12120 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
12130 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
12140 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
12150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12160 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
12170 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
12180 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
12190 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
121a0 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
121b0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
121c0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
121d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
121e0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
121f0 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
12200 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
12210 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
12220 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
12230 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
12240 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
12250 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
12260 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
12270 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
12280 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
12290 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
122a0 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
122b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
122c0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
122d0 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
122e0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
122f0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
12300 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
12310 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
12320 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
12330 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
12340 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
12350 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
12360 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
12370 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
12380 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
12390 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
123a0 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
123b0 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
123c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
123d0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
123e0 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
123f0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
12400 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
12410 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
12420 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
12430 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
12440 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12450 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
12460 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
12470 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
12480 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
12490 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
124a0 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
124b0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
124c0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
124d0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
124e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
124f0 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
12500 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12510 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
12520 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12530 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
12540 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
12550 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
12560 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12570 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
12580 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
12590 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
125a0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
125b0 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
125c0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
125d0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
125e0 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
125f0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
12600 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12610 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
12620 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
12630 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
12640 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
12650 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
12660 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
12670 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
12680 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
12690 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
126a0 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
126b0 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
126c0 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
126d0 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
126e0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
126f0 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
12700 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
12710 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
12720 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
12730 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
12740 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
12750 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
12760 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
12770 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
12780 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
12790 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
127a0 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
127b0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
127c0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
127d0 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
127e0 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
127f0 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
12800 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
12810 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
12820 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
12830 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
12840 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
12850 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
12860 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65  loc and xFree me
12870 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
12880 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
12890 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
128a0 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
128b0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
128c0 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52  brary..** The xR
128d0 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75  ealloc method mu
128e0 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61  st work like rea
128f0 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20  lloc() from the 
12900 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
12910 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65  ry.** with the e
12920 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66  xception that if
12930 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
12940 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63  ment to xRealloc
12950 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65   is zero,.** xRe
12960 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20  alloc must be a 
12970 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20  no-op - it must 
12980 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20  not perform any 
12990 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a  allocation or.**
129a0 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20   deallocation.  
129b0 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
129c0 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
129d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
129e0 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
129f0 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
12a00 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
12a10 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
12a20 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20  p..** And so in 
12a30 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75  cases where xRou
12a40 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75  ndup always retu
12a50 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
12a60 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c  umber,.** xReall
12a70 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65  oc can perform e
12a80 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74  xactly as the st
12a90 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72  andard library r
12aa0 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20  ealloc() and.** 
12ab0 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70  still be in comp
12ac0 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73  liance with this
12ad0 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
12ae0 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
12af0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
12b00 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
12b10 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
12b20 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
12b30 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
12b40 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
12b50 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
12b60 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
12b70 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
12b80 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
12b90 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
12ba0 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
12bb0 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
12bc0 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
12bd0 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
12be0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
12bf0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
12c00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
12c10 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
12c20 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
12c30 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
12c40 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
12c50 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
12c60 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
12c70 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
12c80 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
12c90 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
12ca0 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
12cb0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
12cc0 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
12cd0 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
12ce0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
12cf0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
12d00 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
12d10 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
12d20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
12d30 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
12d40 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
12d50 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
12d60 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
12d70 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
12d80 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
12d90 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
12da0 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
12db0 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
12dc0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
12dd0 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
12de0 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
12df0 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
12e00 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
12e10 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
12e20 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
12e30 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
12e40 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
12e50 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
12e60 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
12e70 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12e80 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
12e90 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
12ea0 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
12eb0 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
12ec0 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
12ed0 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
12ee0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
12ef0 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
12f00 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
12f10 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
12f20 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
12f30 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
12f40 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
12f50 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
12f60 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
12f70 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
12f80 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
12f90 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
12fa0 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
12fb0 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
12fc0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
12fd0 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
12fe0 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
12ff0 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
13000 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
13010 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
13020 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
13030 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
13040 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
13050 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
13060 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
13070 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
13080 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13090 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
130a0 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
130b0 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
130c0 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
130d0 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
130e0 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
130f0 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
13100 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13110 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
13120 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
13130 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
13140 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
13150 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
13160 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
13170 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
13180 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
13190 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
131a0 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
131b0 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
131c0 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
131d0 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
131e0 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
131f0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
13200 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
13210 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
13220 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
13230 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
13240 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
13250 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
13260 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
13270 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
13280 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
13290 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
132a0 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
132b0 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
132c0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
132d0 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
132e0 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
132f0 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
13300 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
13310 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
13320 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
13330 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
13340 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
13350 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
13360 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
13370 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
13380 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
13390 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
133a0 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
133b0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
133c0 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
133d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
133e0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
133f0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
13400 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
13410 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
13420 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
13430 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
13440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
13450 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
13460 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
13470 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
13480 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
13490 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
134a0 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
134b0 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
134c0 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
134d0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
134e0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
134f0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
13500 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
13510 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
13520 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
13530 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
13540 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13550 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
13560 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
13570 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
13580 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
13590 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
135a0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
135b0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
135c0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
135d0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
135e0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
135f0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
13600 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
13610 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
13620 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
13630 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
13640 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
13650 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
13660 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
13670 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
13680 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
13690 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
136a0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
136b0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
136c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
136d0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
136e0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
136f0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
13700 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
13710 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
13720 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
13730 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
13740 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
13750 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
13760 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
13770 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
13780 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
13790 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
137a0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
137b0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
137c0 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
137d0 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
137e0 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
137f0 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
13800 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
13810 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
13820 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13830 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13840 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13850 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13860 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13870 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
13880 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
13890 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
138a0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
138b0 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
138c0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
138d0 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
138e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
138f0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
13900 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
13910 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
13920 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
13930 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
13940 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
13950 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
13960 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13970 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
13980 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13990 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
139a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
139b0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
139c0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
139d0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
139e0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
139f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
13a00 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
13a10 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
13a20 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
13a30 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
13a40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13a50 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13a60 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
13a70 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
13a80 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
13a90 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
13aa0 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
13ab0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
13ac0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
13ad0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13ae0 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
13af0 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
13b00 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
13b10 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
13b20 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
13b30 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
13b40 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
13b50 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
13b60 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
13b70 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
13b80 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
13b90 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
13ba0 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
13bb0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13bc0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13bd0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13be0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13bf0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13c00 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13c10 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
13c20 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
13c30 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
13c40 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
13c50 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
13c60 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
13c70 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
13c80 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
13c90 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
13ca0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
13cb0 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
13cc0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
13cd0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13ce0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
13cf0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13d00 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
13d10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
13d20 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
13d30 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
13d40 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
13d50 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
13d60 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
13d70 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
13d80 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
13d90 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
13da0 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
13db0 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
13dc0 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
13dd0 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
13de0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
13df0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13e00 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
13e10 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
13e20 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
13e30 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
13e40 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13e50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
13e60 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
13e70 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
13e80 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
13e90 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
13ea0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13eb0 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
13ec0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
13ed0 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
13ee0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
13ef0 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
13f00 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
13f10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
13f20 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
13f30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
13f40 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
13f50 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
13f60 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
13f70 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13f80 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13f90 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13fa0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13fb0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13fc0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13fd0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
13fe0 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
13ff0 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
14000 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
14010 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
14020 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
14030 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
14040 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
14050 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
14060 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
14070 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14080 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
14090 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
140a0 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
140b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
140c0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
140d0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
140e0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
140f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
14100 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
14110 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
14120 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
14130 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14140 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
14150 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
14160 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
14170 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
14180 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
14190 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
141a0 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
141b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
141c0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
141d0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
141e0 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
141f0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
14200 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
14210 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
14220 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
14230 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
14240 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
14250 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
14260 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
14270 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14280 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
14290 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
142a0 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
142b0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
142c0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
142d0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
142e0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
142f0 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
14300 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
14310 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
14320 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
14330 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
14340 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
14350 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
14360 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
14370 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
14380 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
14390 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
143a0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
143b0 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
143c0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
143d0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
143e0 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
143f0 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
14400 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
14410 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
14420 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
14430 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
14440 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
14450 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14460 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
14470 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14480 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
14490 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
144a0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
144b0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
144c0 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
144d0 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
144e0 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
144f0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
14500 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
14510 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
14520 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
14530 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
14540 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
14550 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
14560 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
14570 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
14580 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
14590 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
145a0 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
145b0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
145c0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
145d0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
145e0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
145f0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
14600 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
14610 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
14620 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14630 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20  3_status()].**  
14640 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
14650 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
14660 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
14670 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
14680 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
14690 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
146a0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
146b0 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
146c0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
146d0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
146e0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
146f0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
14700 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
14710 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14720 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
14730 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14740 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
14750 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
14760 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
14770 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
14780 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
14790 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
147a0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
147b0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
147c0 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
147d0 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
147e0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
147f0 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
14800 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
14810 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
14820 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
14830 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
14840 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
14850 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
14860 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
14870 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
14880 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20  locations (N).  
14890 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
148a0 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
148b0 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20  tiple of 16..** 
148c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
148d0 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
148e0 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
148f0 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
14900 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
14910 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
14920 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
14930 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
14940 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74  e than two scrat
14950 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
14960 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20  hread.  So.** N 
14970 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
14980 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63   twice the expec
14990 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
149a0 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a  er of threads..*
149b0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
149c0 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73  ever require a s
149d0 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
149e0 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
149f0 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
14a00 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
14a10 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  e. ^If SQLite ne
14a20 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
14a30 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
14a40 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
14a50 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
14a60 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
14a70 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
14a80 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
14a90 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
14aa0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
14ab0 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
14ac0 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
14ad0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
14ae0 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
14af0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14b00 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
14b10 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
14b20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
14b30 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
14b40 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
14b50 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
14b60 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
14b70 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
14b80 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
14b90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
14ba0 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
14bb0 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
14bc0 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
14bd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
14be0 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
14bf0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
14c00 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
14c10 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
14c20 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e  IG_PCACHE option
14c30 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
14c40 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
14c50 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41  o this option: A
14c60 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79   pointer to 8-by
14c70 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65  te aligned.** me
14c80 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
14c90 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
14ca0 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
14cb0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
14cc0 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
14cd0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
14ce0 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
14cf0 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
14d00 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
14d10 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
14d20 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
14d30 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65  8) plus a little
14d40 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a   extra for each.
14d50 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
14d60 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65   ^The page heade
14d70 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20  r size is 20 to 
14d80 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69  40 bytes dependi
14d90 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73  ng on.** the hos
14da0 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20  t architecture. 
14db0 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
14dc0 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
14dd0 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
14de0 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20  ** to make sz a 
14df0 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65  little too large
14e00 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
14e10 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
14e20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
14e30 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
14e40 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
14e50 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
14e60 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
14e70 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
14e80 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
14e90 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
14ea0 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
14eb0 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
14ec0 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
14ed0 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
14ee0 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
14ef0 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
14f00 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
14f10 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
14f20 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
14f30 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
14f40 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
14f50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14f60 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
14f70 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
14f80 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69  pace..** The poi
14f90 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  nter in the firs
14fa0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a  t argument must.
14fb0 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  ** be aligned to
14fc0 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
14fd0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
14fe0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
14ff0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  Lite.** will be 
15000 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
15010 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15020 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74  ONFIG_HEAP]] <dt
15030 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
15040 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
15050 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
15060 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
15070 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
15080 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
15090 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
150a0 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
150b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
150c0 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
150d0 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
150e0 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
150f0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
15100 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
15110 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
15120 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
15130 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d  arguments: An 8-
15140 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
15150 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
15160 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
15170 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
15180 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
15190 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
151a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
151b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
151c0 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
151d0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
151e0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
151f0 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
15200 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
15210 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
15220 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
15230 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
15240 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
15250 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
15260 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
15270 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
15280 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
15290 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
152a0 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
152b0 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
152c0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
152d0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
152e0 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
152f0 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
15300 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
15310 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
15320 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
15330 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
15340 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
15350 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
15360 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
15370 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
15380 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
15390 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
153a0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
153b0 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
153c0 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
153d0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
153e0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
153f0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
15400 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
15410 64 20 61 74 20 32 5e 31 32 2e 20 52 65 61 73 6f  d at 2^12. Reaso
15420 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
15430 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
15440 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
15450 61 72 65 20 32 5e 35 20 74 68 72 6f 75 67 68 20  are 2^5 through 
15460 32 5e 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  2^8.</dd>.**.** 
15470 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15480 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
15490 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
154a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
154b0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
154c0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
154d0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
154e0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
154f0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
15500 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15510 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
15520 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
15530 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
15540 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
15550 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
15560 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
15570 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74  place.** the mut
15580 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
15590 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
155a0 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
155b0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
155c0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
155d0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
155e0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
155f0 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
15600 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
15610 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
15620 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
15630 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
15640 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
15650 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
15660 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
15670 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
15680 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
15690 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
156a0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
156b0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
156c0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
156d0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
156e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
156f0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
15700 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
15710 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
15720 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
15730 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
15740 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15750 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15760 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
15770 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
15780 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15790 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
157a0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
157b0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
157c0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
157d0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
157e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
157f0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
15800 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
15810 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15820 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
15830 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
15840 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
15850 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
15860 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
15870 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
15880 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
15890 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
158a0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
158b0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
158c0 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
158d0 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
158e0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
158f0 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
15900 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
15910 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
15920 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
15930 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
15940 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
15950 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
15960 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
15970 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
15980 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
15990 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
159a0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
159b0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
159c0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
159d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
159e0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
159f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
15a00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15a10 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
15a20 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
15a30 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
15a40 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15a50 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
15a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15a70 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
15a80 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
15a90 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
15aa0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
15ab0 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
15ac0 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
15ad0 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
15ae0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
15af0 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
15b00 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
15b10 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
15b20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15b30 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
15b40 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
15b50 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
15b60 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
15b70 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
15b80 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
15b90 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
15ba0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
15bb0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
15bc0 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
15bd0 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
15be0 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
15bf0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
15c00 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
15c10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
15c20 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
15c30 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
15c40 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
15c50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15c60 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
15c70 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
15c80 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15c90 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
15ca0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15cb0 49 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  IG_PCACHE</dt>.*
15cc0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
15cd0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15ce0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
15cf0 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
15d00 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65  to.** an [sqlite
15d10 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15d20 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
15d30 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
15d40 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
15d50 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
15d60 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
15d70 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c  ntation.)^  ^SQL
15d80 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
15d90 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
15da0 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
15db0 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
15dc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
15dd0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15de0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15df0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
15e00 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15e10 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
15e20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
15e30 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
15e40 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
15e50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
15e60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
15e70 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
15e80 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
15e90 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
15ea0 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
15eb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
15ec0 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
15ed0 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
15ee0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
15ef0 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
15f00 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
15f10 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
15f20 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
15f30 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
15f40 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
15f50 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
15f60 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
15f70 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
15f80 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
15f90 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
15fa0 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
15fb0 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
15fc0 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
15fd0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
15fe0 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
15ff0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
16000 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
16010 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
16020 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
16030 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
16040 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
16050 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
16060 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
16070 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
16080 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
16090 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
160a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
160b0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
160c0 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
160d0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
160e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
160f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
16100 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
16110 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
16120 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
16130 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
16140 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16150 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
16160 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
16170 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
16180 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
16190 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
161a0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
161b0 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
161c0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
161d0 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
161e0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
161f0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
16200 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
16210 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
16220 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
16230 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
16240 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
16250 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
16260 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
16270 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
16280 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
16290 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
162a0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
162b0 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
162c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
162d0 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
162e0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
162f0 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
16300 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
16310 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
16320 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
16330 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
16340 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
16350 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
16360 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16370 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
16380 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
16390 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69  * <dd> This opti
163a0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
163b0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
163c0 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a  pe int. If non-z
163d0 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49  ero, then.** URI
163e0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
163f0 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49  bally enabled. I
16400 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
16410 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  is zero, then UR
16420 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73  I handling.** is
16430 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
16440 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c  ed. If URI handl
16450 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
16460 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
16470 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64  enames.** passed
16480 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
16490 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
164a0 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  pen_v2()], [sqli
164b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
164c0 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
164d0 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
164e0 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
164f0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
16500 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
16510 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
16520 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
16530 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
16540 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
16550 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
16560 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
16570 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c   If it is global
16580 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
16590 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
165a0 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
165b0 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
165c0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
165d0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
165e0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
165f0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
16600 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c  ned. By default,
16610 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
16620 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
16630 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
16640 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
16650 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
16660 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
16670 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
16680 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
16690 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
166a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
166b0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
166c0 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
166d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
166e0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
166f0 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
16700 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16710 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
16720 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
16730 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16740 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
16750 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
16760 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
16770 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16780 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
16790 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
167a0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
167b0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
167c0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
167d0 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
167e0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
167f0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
16800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
16810 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
16820 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
16830 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
16840 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
16850 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
16860 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
16870 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
16880 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16890 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
168a0 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
168b0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
168c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
168d0 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
168e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
168f0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
16900 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16910 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
16920 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
16930 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
16940 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
16950 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
16960 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
16970 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
16980 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16990 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
169a0 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
169b0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
169c0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
169d0 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73  E       14  /* s
169e0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
169f0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16a00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16a10 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
16a20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
16a30 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
16a40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16a50 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
16a60 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
16a70 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
16a80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
16a90 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
16aa0 2f 2a 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  /* int */../*.**
16ab0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
16ac0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
16ad0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
16ae0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
16af0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
16b00 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
16b10 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
16b20 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
16b30 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
16b40 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
16b50 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
16b60 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
16b70 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
16b80 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
16b90 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
16ba0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
16bb0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
16bc0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
16bd0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
16be0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
16bf0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
16c00 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
16c10 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
16c20 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
16c30 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
16c40 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
16c50 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
16c60 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
16c70 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
16c80 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
16c90 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
16ca0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
16cb0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
16cc0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
16cd0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
16ce0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16cf0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
16d00 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
16d10 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
16d20 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16d30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
16d40 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
16d50 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
16d60 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
16d70 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
16d80 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
16d90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
16da0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
16db0 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
16dc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
16dd0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
16de0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
16df0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
16e00 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
16e10 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
16e20 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
16e30 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
16e40 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
16e50 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
16e60 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
16e70 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
16e80 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
16e90 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
16ea0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
16eb0 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
16ec0 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
16ed0 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
16ee0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
16ef0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
16f00 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
16f10 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
16f20 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
16f30 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
16f40 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
16f50 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
16f60 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
16f70 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
16f80 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
16f90 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
16fa0 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
16fb0 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
16fc0 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
16fd0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
16fe0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
16ff0 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
17000 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
17010 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
17020 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
17030 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
17040 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
17050 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
17060 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
17070 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
17080 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
17090 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
170a0 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
170b0 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
170c0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
170d0 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
170e0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
170f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
17100 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
17110 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
17120 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
17130 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
17140 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
17150 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
17160 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
17170 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
17180 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
17190 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
171a0 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
171b0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
171c0 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
171d0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
171e0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
171f0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
17200 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
17210 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
17220 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
17230 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
17240 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
17250 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
17260 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
17270 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
17280 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17290 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
172a0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
172b0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
172c0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
172d0 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
172e0 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
172f0 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
17300 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
17310 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17320 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17330 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17340 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17350 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17360 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
17370 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
17380 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
17390 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
173a0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
173b0 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
173c0 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
173d0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
173e0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
173f0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17400 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17410 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17420 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17430 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
17440 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
17450 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
17460 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
17470 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17480 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
17490 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
174a0 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
174b0 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
174c0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
174d0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
174e0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
174f0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17500 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
17510 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17520 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17530 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
17540 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
17550 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
17560 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
17570 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
17580 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
17590 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
175a0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
175b0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
175c0 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
175d0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
175e0 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
175f0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
17600 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
17610 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
17620 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17630 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
17640 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
17650 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
17660 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
17670 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
17680 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
17690 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
176a0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
176b0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
176c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
176d0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
176e0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
176f0 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
17700 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
17710 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17720 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
17730 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
17740 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
17750 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
17760 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
17770 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
17780 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
17790 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
177a0 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
177b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
177c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
177d0 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
177e0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
177f0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
17800 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
17810 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
17820 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
17830 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
17840 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
17850 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
17860 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
17870 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
17880 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
17890 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
178a0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
178b0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
178c0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
178d0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
178e0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
178f0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54  bility..*/.SQLIT
17900 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
17910 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
17920 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
17930 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
17940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
17950 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
17960 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
17970 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
17980 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
17990 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
179a0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
179b0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
179c0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
179d0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
179e0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
179f0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
17a00 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
17a10 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
17a20 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
17a30 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
17a40 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
17a50 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
17a60 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
17a70 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
17a80 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
17a90 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
17aa0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
17ab0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
17ac0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
17ad0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
17ae0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
17af0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
17b00 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
17b10 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
17b20 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
17b30 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
17b40 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
17b50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17b60 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
17b70 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
17b80 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
17b90 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73  sion 3.7.7, this
17ba0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63   routines.** rec
17bb0 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e  ords the last in
17bc0 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f  sert rowid of bo
17bd0 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c  th ordinary tabl
17be0 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20  es and [virtual 
17bf0 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20  tables]..** ^If 
17c00 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
17c10 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
17c20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
17c30 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
17c40 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
17c50 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
17c60 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
17c70 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
17c80 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77  n a trigger or w
17c90 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c  ithin a [virtual
17ca0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f   table].** metho
17cb0 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  d, then this rou
17cc0 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
17cd0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
17ce0 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
17cf0 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
17d00 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
17d10 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
17d20 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  od is running..*
17d30 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
17d40 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
17d50 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65  l table method e
17d60 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
17d70 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
17d80 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
17d90 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
17da0 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
17db0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17dc0 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  .** table method
17dd0 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20   began.)^.**.** 
17de0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
17df0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
17e00 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
17e10 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
17e20 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
17e30 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
17e40 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
17e50 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
17e60 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
17e70 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
17e80 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
17e90 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
17ea0 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
17eb0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
17ec0 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
17ed0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
17ee0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
17ef0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
17f00 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
17f10 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
17f20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
17f30 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
17f40 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
17f50 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
17f60 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
17f70 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
17f80 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
17f90 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
17fa0 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
17fb0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
17fc0 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
17fd0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
17fe0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
17ff0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
18000 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
18010 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
18020 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
18030 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
18040 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
18050 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
18060 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
18070 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
18080 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
18090 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
180a0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
180b0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
180c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
180d0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
180e0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
180f0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
18100 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
18110 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
18120 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
18130 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
18140 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18150 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
18160 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
18170 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
18180 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
18190 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
181a0 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
181b0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
181c0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
181d0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
181e0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
181f0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
18200 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
18210 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
18220 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
18230 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
18240 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
18250 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
18260 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
18270 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
18280 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
18290 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
182a0 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
182b0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
182c0 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
182d0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
182e0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
182f0 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
18300 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
18310 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
18320 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
18330 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
18340 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
18350 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
18360 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
18370 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
18380 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
18390 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
183a0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
183b0 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
183c0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
183d0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
183e0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
183f0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
18400 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
18410 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
18420 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
18430 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
18440 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
18450 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
18460 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
18470 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
18480 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
18490 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
184a0 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
184b0 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
184c0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
184d0 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
184e0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
184f0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
18500 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
18510 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
18520 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
18530 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
18540 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
18550 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
18560 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
18570 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
18580 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
18590 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
185a0 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
185b0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
185c0 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
185d0 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
185e0 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
185f0 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
18600 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
18610 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
18620 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
18630 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
18640 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
18650 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
18660 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
18670 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
18680 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
18690 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
186a0 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
186b0 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
186c0 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
186d0 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
186e0 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
186f0 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
18700 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
18710 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
18720 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
18730 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
18740 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
18750 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
18760 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
18770 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
18780 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
18790 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
187a0 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
187b0 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
187c0 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
187d0 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
187e0 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
187f0 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
18800 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
18810 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
18820 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
18830 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
18840 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
18850 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
18860 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
18870 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
18880 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
18890 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
188a0 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
188b0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
188c0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
188d0 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
188e0 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
188f0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
18900 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
18910 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
18920 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
18930 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
18940 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
18950 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
18960 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
18970 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
18980 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
18990 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
189a0 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
189b0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
189c0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
189d0 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
189e0 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
189f0 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
18a00 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
18a10 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
18a20 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
18a30 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
18a40 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
18a50 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
18a60 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
18a70 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
18a80 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
18a90 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
18aa0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
18ab0 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
18ac0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
18ad0 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
18ae0 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
18af0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
18b00 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
18b10 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
18b20 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
18b30 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
18b40 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
18b50 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
18b60 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
18b70 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
18b80 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
18b90 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
18ba0 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
18bb0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
18bc0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
18bd0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
18be0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
18bf0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
18c00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
18c10 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
18c20 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
18c30 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
18c40 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
18c50 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
18c60 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
18c70 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
18c80 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
18c90 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
18ca0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18cb0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
18cc0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
18cd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
18ce0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
18cf0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
18d00 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
18d10 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
18d20 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
18d30 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
18d40 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
18d50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
18d60 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
18d70 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
18d80 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
18d90 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
18da0 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
18db0 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
18dc0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
18dd0 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
18de0 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
18df0 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
18e00 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
18e10 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
18e20 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
18e30 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
18e40 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
18e50 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
18e60 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
18e70 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
18e80 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
18e90 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
18ea0 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
18eb0 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
18ec0 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
18ed0 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
18ee0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
18ef0 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
18f00 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
18f10 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
18f20 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
18f30 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
18f40 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
18f50 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
18f60 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
18f70 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
18f80 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
18f90 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
18fa0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
18fb0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
18fc0 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
18fd0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
18fe0 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
18ff0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
19000 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
19010 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
19020 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
19030 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
19040 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
19050 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
19060 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
19070 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
19080 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
19090 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
190a0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
190b0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
190c0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
190d0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
190e0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
190f0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
19100 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
19110 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
19120 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
19130 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
19140 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
19150 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
19160 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
19170 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
19180 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
19190 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
191a0 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
191b0 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
191c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
191d0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
191e0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
191f0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
19200 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
19210 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
19220 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
19230 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
19240 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
19250 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
19260 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
19270 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
19280 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
19290 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
192a0 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
192b0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
192c0 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
192d0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
192e0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
192f0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
19300 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
19310 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
19320 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
19330 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
19340 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
19350 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
19360 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
19370 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
19380 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
19390 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
193a0 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
193b0 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
193c0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
193d0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
193e0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
193f0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
19400 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
19410 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
19420 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
19430 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
19440 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
19450 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
19460 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
19470 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
19480 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
19490 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
194a0 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
194b0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
194c0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
194d0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
194e0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
194f0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
19500 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
19510 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
19520 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
19530 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
19540 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
19550 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
19560 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
19570 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
19580 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
19590 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
195a0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
195b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
195c0 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
195d0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
195e0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
195f0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
19600 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
19610 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
19620 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
19630 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
19640 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
19650 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
19660 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
19670 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
19680 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
19690 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
196a0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
196b0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
196c0 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
196d0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
196e0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
196f0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
19700 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
19710 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
19720 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
19730 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
19740 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
19750 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
19760 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
19770 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
19780 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
19790 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
197a0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
197b0 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
197c0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
197d0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
197e0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
197f0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
19800 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
19810 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
19820 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
19830 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
19840 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
19850 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
19860 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
19870 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
19880 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
19890 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
198a0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
198b0 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
198c0 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53  ely happen..*/.S
198d0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
198e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
198f0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
19900 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
19910 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
19920 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
19930 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
19940 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
19950 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
19960 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
19970 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
19980 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
19990 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
199a0 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
199b0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
199c0 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
199d0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
199e0 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
199f0 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
19a00 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
19a10 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
19a20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
19a30 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
19a40 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
19a50 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
19a60 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
19a70 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
19a80 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
19a90 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
19aa0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
19ab0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
19ac0 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
19ad0 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
19ae0 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
19af0 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
19b00 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
19b10 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
19b20 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
19b30 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
19b40 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
19b50 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
19b60 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
19b70 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
19b80 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
19b90 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
19ba0 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
19bb0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
19bc0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
19bd0 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
19be0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
19bf0 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
19c00 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
19c10 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
19c20 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
19c30 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
19c40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
19c50 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
19c60 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
19c70 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
19c80 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
19c90 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
19ca0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
19cb0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
19cc0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
19cd0 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
19ce0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
19cf0 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
19d00 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
19d10 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
19d20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
19d30 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
19d40 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
19d50 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
19d60 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
19d70 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
19d80 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
19d90 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
19da0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
19db0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
19dc0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
19dd0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19de0 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
19df0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
19e00 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
19e10 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
19e20 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
19e30 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
19e40 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
19e50 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
19e60 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
19e70 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
19e80 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
19e90 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
19ea0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
19eb0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
19ec0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
19ed0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
19ee0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
19ef0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19f00 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
19f10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
19f20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
19f30 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
19f40 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  der..*/.SQLITE_A
19f50 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
19f60 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
19f70 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45  ar *sql);.SQLITE
19f80 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
19f90 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
19fa0 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
19fb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
19fc0 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
19fd0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
19fe0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
19ff0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1a000 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
1a010 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
1a020 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
1a030 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
1a040 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1a050 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
1a060 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
1a070 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
1a080 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
1a090 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
1a0a0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1a0b0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
1a0c0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
1a0d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
1a0e0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
1a0f0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1a100 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
1a110 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
1a120 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
1a130 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
1a140 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
1a150 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
1a160 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1a170 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
1a180 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1a190 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1a1a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1a1b0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
1a1c0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
1a1d0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
1a1e0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
1a1f0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1a200 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
1a210 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
1a220 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1a230 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
1a240 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
1a250 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
1a260 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
1a270 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
1a280 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
1a290 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
1a2a0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
1a2b0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1a2c0 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
1a2d0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
1a2e0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
1a2f0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
1a300 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
1a310 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
1a320 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
1a330 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
1a340 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1a350 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
1a360 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
1a370 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
1a380 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
1a390 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
1a3a0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
1a3b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
1a3c0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
1a3d0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
1a3e0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
1a3f0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
1a400 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
1a410 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
1a420 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
1a430 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
1a440 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
1a450 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
1a460 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
1a470 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
1a480 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
1a490 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
1a4a0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
1a4b0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
1a4c0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
1a4d0 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
1a4e0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
1a4f0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
1a500 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
1a510 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
1a520 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
1a530 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
1a540 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
1a550 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
1a560 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
1a570 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
1a580 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
1a590 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
1a5a0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
1a5b0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
1a5c0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
1a5d0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
1a5e0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
1a5f0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1a600 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
1a610 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1a620 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
1a630 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
1a640 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
1a650 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
1a660 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
1a670 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
1a680 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
1a690 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
1a6a0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
1a6b0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
1a6c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
1a6d0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
1a6e0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
1a6f0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
1a700 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
1a710 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
1a720 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
1a730 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
1a740 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1a750 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
1a760 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1a770 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
1a780 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1a790 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
1a7a0 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
1a7b0 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
1a7c0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
1a7d0 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
1a7e0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
1a7f0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
1a800 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
1a810 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
1a820 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
1a830 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
1a840 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
1a850 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
1a860 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
1a870 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
1a880 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
1a890 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
1a8a0 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
1a8b0 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
1a8c0 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
1a8d0 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
1a8e0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
1a8f0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
1a900 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
1a910 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
1a920 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
1a930 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
1a940 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
1a950 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
1a960 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
1a970 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
1a980 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
1a990 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
1a9a0 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
1a9b0 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
1a9c0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
1a9d0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
1a9e0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
1a9f0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
1aa00 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
1aa10 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
1aa20 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
1aa30 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
1aa40 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
1aa50 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
1aa60 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
1aa70 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
1aa80 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
1aa90 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
1aaa0 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
1aab0 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
1aac0 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
1aad0 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
1aae0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
1aaf0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1ab00 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1ab10 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1ab20 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1ab30 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1ab40 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1ab50 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1ab60 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1ab70 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1ab80 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1ab90 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1aba0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1abb0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
1abc0 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
1abd0 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
1abe0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
1abf0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
1ac00 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
1ac10 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
1ac20 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
1ac30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ac40 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1ac50 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1ac60 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
1ac70 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
1ac80 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
1ac90 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
1aca0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
1acb0 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
1acc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1acd0 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
1ace0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1acf0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1ad00 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53  sy handler..*/.S
1ad10 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1ad20 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1ad30 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
1ad40 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
1ad50 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1ad60 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
1ad70 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
1ad80 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1ad90 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
1ada0 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
1adb0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
1adc0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
1add0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
1ade0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
1adf0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
1ae00 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
1ae10 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
1ae20 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
1ae30 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
1ae40 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1ae50 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
1ae60 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
1ae70 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
1ae80 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1ae90 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
1aea0 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
1aeb0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
1aec0 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
1aed0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
1aee0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1aef0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
1af00 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
1af10 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1af20 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1af30 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1af40 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1af50 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1af60 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1af70 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1af80 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1af90 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1afa0 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1afb0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1afc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1afd0 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
1afe0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
1aff0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
1b000 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
1b010 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
1b020 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
1b030 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
1b040 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
1b050 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
1b060 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
1b070 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  red.)^.*/.SQLITE
1b080 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1b090 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1b0a0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1b0b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b0c0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1b0d0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1b0e0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
1b0f0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1b100 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1b110 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1b120 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1b130 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1b140 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1b150 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1b160 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1b170 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1b180 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1b190 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1b1a0 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1b1b0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1b1c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1b1d0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1b1e0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1b1f0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1b200 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1b210 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1b220 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1b230 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1b240 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1b250 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1b260 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1b270 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1b280 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1b290 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1b2a0 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1b2b0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1b2c0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1b2d0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1b2e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1b2f0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1b300 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1b310 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1b320 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1b330 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1b340 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1b350 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1b360 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1b370 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1b380 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1b390 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1b3a0 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1b3b0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1b3c0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1b3d0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1b3e0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1b3f0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1b400 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1b410 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1b420 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1b430 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1b440 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1b450 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1b460 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1b470 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1b480 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1b490 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1b4a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1b4b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1b4c0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1b4d0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1b4e0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1b4f0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1b500 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1b510 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1b520 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1b530 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1b540 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b550 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1b560 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1b570 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1b580 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1b590 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1b5a0 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1b5b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1b5c0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1b5d0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1b5e0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1b5f0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1b600 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b610 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1b620 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1b630 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1b640 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1b650 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1b660 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1b670 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1b680 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1b690 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1b6a0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b6b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1b6c0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1b6d0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1b6e0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1b6f0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1b700 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1b710 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1b720 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1b730 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1b740 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1b750 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1b760 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1b770 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1b780 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b790 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1b7a0 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1b7b0 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1b7c0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1b7d0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1b7e0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b7f0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1b800 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b810 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1b820 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b830 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1b840 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b850 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1b860 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1b870 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1b880 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1b890 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b8a0 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1b8b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b8c0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1b8d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1b8e0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1b8f0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1b900 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1b910 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1b920 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1b930 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1b940 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1b950 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1b960 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1b970 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1b980 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1b990 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1b9a0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1b9b0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1b9c0 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1b9d0 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1b9e0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1b9f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1ba00 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1ba10 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1ba20 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1ba30 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1ba40 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1ba50 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1ba60 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1ba70 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1ba80 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1ba90 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1baa0 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1bab0 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1bac0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1bad0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1bae0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1baf0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1bb00 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1bb10 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1bb20 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1bb30 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1bb40 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1bb50 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1bb60 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1bb70 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1bb80 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1bb90 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1bba0 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1bbb0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1bbc0 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1bbd0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1bbe0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1bbf0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1bc00 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1bc10 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1bc20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1bc30 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1bc40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1bc50 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1bc60 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1bc70 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1bc80 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1bc90 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1bca0 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1bcb0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1bcc0 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1bcd0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1bce0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1bcf0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1bd00 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1bd10 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1bd20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1bd30 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1bd40 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1bd50 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1bd60 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1bd70 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1bd80 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1bd90 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1bda0 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1bdb0 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1bdc0 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1bdd0 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1bde0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1bdf0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1be00 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1be10 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1be20 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1be30 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1be40 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1be50 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1be60 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1be70 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1be80 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1be90 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
1bea0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  I void sqlite3_f
1beb0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1bec0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1bed0 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1bee0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1bef0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1bf00 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1bf10 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1bf20 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1bf30 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1bf40 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1bf50 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1bf60 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
1bf70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1bf80 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1bf90 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1bfa0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1bfb0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1bfc0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1bfd0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1bfe0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1bff0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1c000 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1c010 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1c020 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1c030 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1c040 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1c050 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1c060 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1c070 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1c080 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1c090 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1c0a0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1c0b0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1c0c0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1c0d0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1c0e0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1c0f0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1c100 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1c110 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1c120 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1c130 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1c140 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1c150 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1c160 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1c170 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1c180 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1c190 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1c1a0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1c1b0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1c1c0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1c1d0 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1c1e0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1c1f0 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1c200 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1c210 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1c220 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1c230 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1c240 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1c250 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1c260 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1c270 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1c280 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1c290 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1c2a0 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1c2b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1c2c0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1c2d0 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1c2e0 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1c2f0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1c300 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1c310 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1c320 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1c330 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1c340 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1c350 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1c360 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1c370 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1c380 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1c390 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1c3a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1c3b0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1c3c0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1c3d0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1c3e0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1c3f0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1c400 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1c410 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1c420 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1c430 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1c440 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1c450 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1c460 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1c470 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1c480 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1c490 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1c4a0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1c4b0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1c4c0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1c4d0 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1c4e0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1c4f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c500 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1c510 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1c520 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1c530 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1c540 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1c550 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1c560 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1c570 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1c580 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1c590 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1c5a0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1c5b0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1c5c0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1c5d0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1c5e0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1c5f0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1c600 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1c610 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
1c620 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1c630 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1c640 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1c650 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1c660 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
1c670 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1c680 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
1c690 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
1c6a0 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
1c6b0 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
1c6c0 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
1c6d0 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
1c6e0 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
1c6f0 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
1c700 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
1c710 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
1c720 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
1c730 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
1c740 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
1c750 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
1c760 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
1c770 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
1c780 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
1c790 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
1c7a0 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
1c7b0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1c7c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1c7d0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
1c7e0 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
1c7f0 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
1c800 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1c810 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
1c820 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
1c830 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1c840 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1c850 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1c860 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1c870 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1c880 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1c890 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
1c8a0 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
1c8b0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1c8c0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1c8d0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1c8e0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1c8f0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1c900 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
1c910 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
1c920 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
1c930 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
1c940 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
1c950 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
1c960 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
1c970 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1c980 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1c990 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1c9a0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1c9b0 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
1c9c0 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
1c9d0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1c9e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
1c9f0 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
1ca00 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
1ca10 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
1ca20 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
1ca30 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
1ca40 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
1ca50 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1ca60 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1ca70 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1ca80 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1ca90 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
1caa0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1cab0 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
1cac0 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
1cad0 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
1cae0 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
1caf0 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
1cb00 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
1cb10 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
1cb20 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
1cb30 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
1cb40 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
1cb50 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
1cb60 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
1cb70 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
1cb80 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
1cb90 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
1cba0 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
1cbb0 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
1cbc0 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
1cbd0 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
1cbe0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
1cbf0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1cc00 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
1cc10 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
1cc20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
1cc30 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
1cc40 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
1cc50 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
1cc60 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1cc70 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1cc80 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1cc90 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1cca0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1ccb0 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
1ccc0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1ccd0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1cce0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1ccf0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1cd00 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1cd10 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
1cd20 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
1cd30 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
1cd40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1cd50 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
1cd60 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
1cd70 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
1cd80 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1cd90 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
1cda0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
1cdb0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1cdc0 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
1cdd0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
1cde0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
1cdf0 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
1ce00 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
1ce10 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
1ce20 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1ce30 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
1ce40 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1ce50 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
1ce60 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1ce70 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1ce80 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  ar*,...);.SQLITE
1ce90 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1cea0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1ceb0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1cec0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1ced0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1cee0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1cef0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1cf00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1cf10 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1cf20 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1cf30 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1cf40 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1cf50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1cf60 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1cf70 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1cf80 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1cf90 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1cfa0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1cfb0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1cfc0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1cfd0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1cfe0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1cff0 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1d000 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1d010 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1d020 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1d030 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1d040 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1d050 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1d060 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1d070 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1d080 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1d090 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d0a0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1d0b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1d0c0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1d0d0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1d0e0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1d0f0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1d100 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1d110 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d120 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1d130 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1d140 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1d150 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1d160 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1d170 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1d180 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1d190 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1d1a0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1d1b0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d1c0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1d1d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1d1e0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1d1f0 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1d200 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1d210 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1d220 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1d230 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1d240 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1d250 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1d260 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1d270 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1d280 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1d290 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1d2a0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1d2b0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1d2c0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1d2d0 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1d2e0 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1d2f0 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1d300 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1d310 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1d320 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1d330 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1d340 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1d350 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1d360 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1d370 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1d380 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1d390 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1d3a0 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1d3b0 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1d3c0 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1d3d0 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1d3e0 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1d3f0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1d400 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1d410 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1d420 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1d430 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1d440 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1d450 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d460 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1d470 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  loc()..**.** ^(T
1d480 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1d490 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
1d4a0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
1d4b0 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
1d4c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1d4d0 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
1d4e0 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
1d4f0 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
1d500 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
1d510 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d520 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
1d530 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
1d540 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49  parameter.)^ ^ I
1d550 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
1d560 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1d570 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
1d580 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1d590 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1d5a0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1d5b0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1d5c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
1d5d0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1d5e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1d5f0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1d600 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  c()..** ^If the 
1d610 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1d620 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1d630 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1d640 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1d650 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1d660 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1d670 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1d680 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
1d690 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
1d6a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1d6b0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1d6c0 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  oc()..** ^sqlite
1d6d0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
1d6e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1d6f0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1d700 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1d710 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1d720 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
1d730 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1d740 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
1d750 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1d760 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1d770 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1d780 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1d790 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1d7a0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1d7b0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1d7c0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1d7d0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1d7e0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1d7f0 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70  lloc() and the p
1d800 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1d810 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
1d820 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d830 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
1d840 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
1d850 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
1d860 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1d870 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1d880 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1d890 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73  3_malloc() and s
1d8a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d8b0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
1d8c0 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
1d8d0 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
1d8e0 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a  dary, or to a.**
1d8f0 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   4 byte boundary
1d900 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1d910 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d  4_BYTE_ALIGNED_M
1d920 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74  ALLOC] compile-t
1d930 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  ime.** option is
1d940 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20   used..**.** In 
1d950 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1d960 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
1d970 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
1d980 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
1d990 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
1d9a0 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
1d9b0 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
1d9c0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
1d9d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1d9e0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1d9f0 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
1da00 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
1da10 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
1da20 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
1da30 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
1da40 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
1da50 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
1da60 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  The Windows OS i
1da70 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
1da80 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74  alls.** the syst
1da90 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1daa0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1dab0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1dac0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1dad0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1dae0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1daf0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1db00 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1db10 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1db20 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1db30 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1db40 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1db50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1db60 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74  rrors are detect
1db70 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1db80 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  are reported bac
1db90 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1dba0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1dbb0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1dbc0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1dbd0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1dbe0 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1dbf0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1dc00 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1dc10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1dc20 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1dc30 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1dc40 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1dc50 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1dc60 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1dc70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1dc80 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1dc90 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1dca0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1dcb0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1dcc0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1dcd0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1dce0 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1dcf0 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1dd00 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1dd10 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1dd20 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1dd30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1dd40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1dd50 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  loc()]..*/.SQLIT
1dd60 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1dd70 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1dd80 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1dd90 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1dda0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53  c(void*, int);.S
1ddb0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1ddc0 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1ddd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1dde0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1ddf0 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
1de00 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
1de10 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
1de20 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
1de30 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
1de40 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
1de50 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
1de60 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
1de70 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
1de80 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1de90 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
1dea0 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
1deb0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1dec0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
1ded0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
1dee0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1def0 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
1df00 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1df10 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
1df20 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
1df30 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
1df40 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
1df50 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
1df60 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1df70 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
1df80 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
1df90 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
1dfa0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
1dfb0 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
1dfc0 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1dfd0 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
1dfe0 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
1dff0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1e000 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1e010 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1e020 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1e030 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
1e040 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
1e050 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
1e060 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
1e070 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
1e080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1e090 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
1e0a0 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
1e0b0 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
1e0c0 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
1e0d0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1e0e0 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
1e0f0 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
1e100 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1e110 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1e120 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
1e130 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1e140 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
1e150 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
1e160 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
1e170 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1e180 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1e190 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
1e1a0 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
1e1b0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
1e1c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1e1d0 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
1e1e0 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
1e1f0 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
1e200 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
1e210 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1e220 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1e230 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1e240 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  d);.SQLITE_API s
1e250 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1e260 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1e270 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1e280 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1e290 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1e2a0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1e2b0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1e2c0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1e2d0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1e2e0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1e2f0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1e300 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1e310 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1e320 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1e330 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1e340 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1e350 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
1e360 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
1e370 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
1e380 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
1e390 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
1e3a0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
1e3b0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
1e3c0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
1e3d0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
1e3e0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1e3f0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
1e400 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
1e410 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
1e420 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
1e430 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
1e440 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1e450 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
1e460 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
1e470 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fer P..**.** ^Th
1e480 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
1e490 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
1e4a0 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
1e4b0 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
1e4c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1e4d0 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
1e4e0 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
1e4f0 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
1e500 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
1e510 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
1e520 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1e530 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1e540 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75  t..** ^On all su
1e550 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
1e560 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
1e570 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1e580 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1e590 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1e5a0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1e5b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1e5c0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1e5d0 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54  method..*/.SQLIT
1e5e0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1e5f0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
1e600 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
1e610 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e620 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
1e630 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
1e640 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
1e650 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
1e660 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
1e670 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
1e680 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1e690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e6a0 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
1e6b0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
1e6c0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
1e6d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e6e0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
1e6f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
1e700 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
1e710 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1e720 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1e730 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
1e740 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e750 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1e760 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
1e770 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e780 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
1e790 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
1e7a0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
1e7b0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
1e7c0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
1e7d0 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
1e7e0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
1e7f0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
1e800 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e810 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
1e820 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
1e830 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
1e840 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
1e850 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e860 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
1e870 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
1e880 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
1e890 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
1e8a0 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
1e8b0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
1e8c0 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
1e8d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1e8e0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
1e8f0 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
1e900 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1e910 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
1e920 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
1e930 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
1e940 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
1e950 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
1e960 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e970 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
1e980 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1e990 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1e9a0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
1e9b0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
1e9c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
1e9d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e9e0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1e9f0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1ea00 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
1ea10 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1ea20 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1ea30 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
1ea40 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1ea50 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1ea60 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
1ea70 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
1ea80 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
1ea90 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
1eaa0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1eab0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
1eac0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1ead0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1eae0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1eaf0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
1eb00 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
1eb10 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1eb20 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
1eb30 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
1eb40 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
1eb50 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
1eb60 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1eb70 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1eb80 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
1eb90 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
1eba0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1ebb0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
1ebc0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
1ebd0 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
1ebe0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
1ebf0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1ec00 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1ec10 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1ec20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
1ec30 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
1ec40 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
1ec50 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1ec60 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
1ec70 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
1ec80 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
1ec90 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
1eca0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1ecb0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
1ecc0 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
1ecd0 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
1ece0 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
1ecf0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
1ed00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
1ed10 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1ed20 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
1ed30 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1ed40 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
1ed50 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
1ed60 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1ed70 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
1ed80 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
1ed90 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
1eda0 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
1edb0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
1edc0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
1edd0 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
1ede0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
1edf0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
1ee00 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1ee10 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
1ee20 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
1ee30 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
1ee40 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
1ee50 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
1ee60 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
1ee70 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
1ee80 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1ee90 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
1eea0 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
1eeb0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1eec0 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
1eed0 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
1eee0 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
1eef0 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
1ef00 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
1ef10 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
1ef20 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
1ef30 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
1ef40 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
1ef50 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
1ef60 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
1ef70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1ef80 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
1ef90 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
1efa0 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
1efb0 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
1efc0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
1efd0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
1efe0 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
1eff0 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
1f000 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
1f010 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
1f020 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
1f030 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
1f040 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
1f050 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
1f060 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
1f070 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
1f080 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
1f090 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
1f0a0 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
1f0b0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
1f0c0 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
1f0d0 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
1f0e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1f0f0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
1f100 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
1f110 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
1f120 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
1f130 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1f140 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
1f150 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
1f160 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
1f170 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
1f180 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
1f190 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1f1a0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
1f1b0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
1f1c0 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
1f1d0 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
1f1e0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
1f1f0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1f200 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
1f210 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
1f220 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
1f230 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
1f240 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
1f250 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
1f260 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1f270 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
1f280 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
1f290 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
1f2a0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1f2b0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
1f2c0 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
1f2d0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
1f2e0 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
1f2f0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
1f300 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
1f310 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1f320 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
1f330 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
1f340 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
1f350 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
1f360 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
1f370 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
1f380 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
1f390 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
1f3a0 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
1f3b0 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
1f3c0 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
1f3d0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
1f3e0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1f3f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1f400 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1f410 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1f420 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1f430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1f440 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
1f450 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f460 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
1f470 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f480 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1f490 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1f4a0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1f4b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f4c0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1f4d0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1f4e0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1f4f0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
1f500 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f510 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
1f520 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
1f530 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
1f540 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
1f550 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
1f560 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
1f570 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
1f580 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
1f590 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
1f5a0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
1f5b0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1f5c0 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
1f5d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f5e0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
1f5f0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
1f600 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1f610 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
1f620 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f630 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1f640 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
1f650 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f660 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1f670 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
1f680 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
1f690 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
1f6a0 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
1f6b0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
1f6c0 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
1f6d0 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
1f6e0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
1f6f0 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
1f700 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
1f710 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
1f720 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
1f730 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1f740 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
1f750 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54  change..*/.SQLIT
1f760 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1f770 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1f780 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1f790 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1f7a0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1f7b0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1f7c0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1f7d0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1f7e0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1f7f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1f800 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1f810 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1f820 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1f830 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1f840 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1f850 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1f860 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1f870 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1f880 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1f890 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1f8a0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1f8b0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1f8c0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1f8d0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1f8e0 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1f8f0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1f900 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1f910 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1f920 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1f930 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1f940 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1f950 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1f960 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51  so used as a [SQ
1f970 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
1f980 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20  return code].** 
1f990 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
1f9a0 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
1f9b0 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
1f9c0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1f9d0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1f9e0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1f9f0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1fa00 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1fa10 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1fa20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1fa30 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1fa40 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1fa50 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1fa60 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1fa70 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1fa80 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1fa90 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1faa0 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1fab0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1fac0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1fad0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1fae0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1faf0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1fb00 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1fb10 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1fb20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1fb30 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1fb40 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1fb50 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1fb60 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1fb70 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1fb80 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1fb90 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1fba0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1fbb0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1fbc0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1fbd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1fbe0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1fbf0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1fc00 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1fc10 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1fc20 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1fc30 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1fc40 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1fc50 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1fc60 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1fc70 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1fc80 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1fc90 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1fca0 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1fcb0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1fcc0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
1fcd0 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
1fce0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1fcf0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1fd00 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1fd10 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1fd20 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1fd30 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1fd40 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
1fd50 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1fd60 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1fd70 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
1fd80 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
1fd90 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
1fda0 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
1fdb0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
1fdc0 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
1fdd0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
1fde0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
1fdf0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
1fe00 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
1fe10 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
1fe20 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
1fe30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fe40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
1fe50 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
1fe60 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
1fe70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1fe80 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
1fe90 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
1fea0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1feb0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1fec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1fed0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
1fee0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
1fef0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1ff00 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ff10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1ff20 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
1ff30 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
1ff40 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1ff50 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ff60 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ff70 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
1ff80 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
1ff90 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ffa0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ffb0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ffc0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1ffd0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
1ffe0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1fff0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
20000 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
20010 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
20020 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
20030 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20040 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20050 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
20060 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
20070 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
20080 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
20090 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
200a0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
200b0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
200c0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
200d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
200e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
200f0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
20100 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
20110 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20120 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20130 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20140 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
20150 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
20160 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
20170 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
20180 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20190 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
201a0 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
201b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
201c0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
201d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
201e0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
201f0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
20200 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
20210 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20230 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
20240 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
20250 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
20260 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20270 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20280 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
20290 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
202a0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
202b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
202c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
202d0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
202e0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
202f0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
20300 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20320 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
20330 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
20340 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
20350 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
20360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20370 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
20380 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
20390 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
203a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
203b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
203c0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
203d0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
203e0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
203f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20400 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
20410 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
20420 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
20430 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
20440 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
20450 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
20460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20470 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
20480 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
20490 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
204a0 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
204b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
204c0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
204d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
204e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
204f0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
20500 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
20510 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
20520 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20530 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20540 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
20550 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
20560 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20570 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
20580 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20590 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
205a0 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
205b0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
205c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
205d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
205e0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
205f0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
20600 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
20610 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20620 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20630 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
20640 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
20650 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
20660 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
20670 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20680 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
20690 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
206a0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
206b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
206c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
206d0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
206e0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
206f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20700 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20710 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20720 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
20730 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
20740 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
20750 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
20760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20770 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
20780 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
20790 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
207a0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
207b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
207c0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
207d0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
207e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
207f0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
20800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
20810 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
20820 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
20830 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
20840 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
20850 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
20860 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
20870 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
20880 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
20890 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
208a0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
208b0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
208c0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
208d0 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
208e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
208f0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
20900 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
20910 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
20920 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
20930 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
20940 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
20950 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
20960 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
20970 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
20980 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
20990 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
209a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
209b0 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
209c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
209d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
209e0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
209f0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
20a00 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
20a10 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
20a20 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
20a30 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
20a40 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
20a50 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
20a60 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
20a70 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
20a80 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
20a90 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
20aa0 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
20ab0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
20ac0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
20ad0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
20ae0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
20af0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
20b00 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
20b10 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
20b20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
20b30 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
20b40 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
20b50 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
20b60 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
20b70 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
20b80 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
20b90 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
20ba0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
20bb0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
20bc0 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
20bd0 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
20be0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
20bf0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
20c00 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
20c10 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
20c20 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
20c30 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
20c40 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
20c50 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
20c60 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
20c70 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
20c80 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
20c90 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
20ca0 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
20cb0 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
20cc0 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
20cd0 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
20ce0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
20cf0 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
20d00 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
20d10 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
20d20 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
20d30 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
20d40 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
20d50 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
20d60 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
20d70 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
20d80 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
20d90 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
20da0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
20db0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
20dc0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
20dd0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
20de0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
20df0 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
20e00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
20e10 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
20e20 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
20e30 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
20e40 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
20e50 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
20e60 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
20e70 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
20e80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20e90 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
20ea0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
20eb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
20ec0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
20ed0 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
20ee0 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
20ef0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
20f00 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
20f10 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
20f20 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
20f30 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
20f40 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
20f50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20f60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
20f70 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
20f80 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
20f90 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
20fa0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
20fb0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
20fc0 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
20fd0 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
20fe0 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
20ff0 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
21000 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
21010 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
21020 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
21030 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
21040 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
21050 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
21060 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
21070 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63  .** [virtual mac
21080 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e  hine instruction
21090 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c  s] that are eval
210a0 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75  uated between su
210b0 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f  ccessive.** invo
210c0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63  cations of the c
210d0 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a  allback X..**.**
210e0 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
210f0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
21100 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
21110 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
21120 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
21130 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
21140 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
21150 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
21160 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
21170 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
21180 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
21190 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
211a0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
211b0 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
211c0 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
211d0 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
211e0 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
211f0 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
21200 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
21210 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
21220 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
21230 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
21240 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
21250 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
21260 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
21270 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
21280 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
21290 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
212a0 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
212b0 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
212c0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
212d0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
212e0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
212f0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
21300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21310 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
21320 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
21330 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
21340 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
21350 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
21360 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
21370 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
21380 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
21390 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
213a0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
213b0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
213c0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c  graph..**.*/.SQL
213d0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
213e0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
213f0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
21400 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
21410 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
21420 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
21430 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
21440 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
21450 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
21460 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
21470 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
21480 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62  e as specified b
21490 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61  y the .** filena
214a0 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68  me argument. ^Th
214b0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
214c0 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
214d0 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
214e0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
214f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
21500 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
21510 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
21520 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
21530 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
21540 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74  en16(). ^(A [dat
21550 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21560 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
21570 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
21580 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
21590 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
215a0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
215b0 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
215c0 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
215d0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
215e0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
215f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
21600 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
21610 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
21620 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
21630 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
21640 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
21650 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e  ].** object.)^ ^
21660 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  (If the database
21670 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
21680 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
21690 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
216a0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
216b0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
216c0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
216d0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
216e0 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71  d.)^ ^The.** [sq
216f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
21700 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
21710 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
21720 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
21730 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
21740 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
21750 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
21760 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67   error following
21770 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e   a failure of an
21780 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  y.** of the sqli
21790 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69  te3_open() routi
217a0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nes..**.** ^The 
217b0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
217c0 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
217d0 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  e will be UTF-8 
217e0 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  if.** sqlite3_op
217f0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
21800 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c  open_v2() is cal
21810 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31  led and.** UTF-1
21820 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
21830 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71  byte order if sq
21840 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69  lite3_open16() i
21850 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68  s used..**.** Wh
21860 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
21870 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
21880 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
21890 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
218a0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
218b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
218c0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
218d0 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
218e0 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
218f0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
21900 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
21910 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
21920 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
21930 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21940 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
21950 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
21960 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
21970 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
21980 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
21990 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
219a0 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
219b0 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
219c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
219d0 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
219e0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
219f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
21a00 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
21a10 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
21a20 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
21a30 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
21a40 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
21a50 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
21a60 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
21a70 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
21a80 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
21a90 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
21aa0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
21ab0 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
21ac0 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
21ad0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
21ae0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
21af0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
21b00 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
21b10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
21b20 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
21b30 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
21b40 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
21b50 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
21b60 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
21b70 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
21b80 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
21b90 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
21ba0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
21bb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
21bc0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
21bd0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
21be0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
21bf0 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
21c00 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
21c10 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
21c20 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
21c30 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
21c40 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
21c50 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
21c60 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
21c70 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
21c80 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
21c90 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
21ca0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
21cb0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
21cc0 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
21cd0 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
21ce0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
21cf0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
21d00 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
21d10 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
21d20 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
21d30 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
21d40 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
21d50 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
21d60 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
21d70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
21d80 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
21d90 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
21da0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
21db0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
21dc0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
21dd0 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
21de0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
21df0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
21e00 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
21e10 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
21e20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
21e30 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
21e40 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
21e50 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
21e60 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
21e70 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
21e80 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
21e90 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
21ea0 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
21eb0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21ec0 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
21ed0 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
21ee0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
21ef0 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
21f00 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
21f10 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
21f20 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
21f30 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
21f40 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
21f50 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
21f60 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
21f70 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
21f80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21f90 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
21fa0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
21fb0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
21fc0 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
21fd0 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
21fe0 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
21ff0 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
22000 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
22010 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
22020 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
22030 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
22040 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
22050 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
22060 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
22070 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
22080 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
22090 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
220a0 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
220b0 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
220c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
220d0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
220e0 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
220f0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
22100 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
22110 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
22120 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
22130 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
22140 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
22150 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
22160 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
22170 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
22180 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
22190 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
221a0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
221b0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
221c0 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
221d0 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
221e0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
221f0 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
22200 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
22210 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
22220 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
22230 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
22240 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
22250 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
22260 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
22270 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
22280 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
22290 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
222a0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
222b0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
222c0 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
222d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
222e0 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
222f0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
22300 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
22310 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
22320 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
22330 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22340 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
22350 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
22360 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
22370 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
22380 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
22390 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
223a0 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
223b0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
223c0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
223d0 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
223e0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
223f0 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
22400 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
22410 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
22420 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
22430 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
22440 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
22450 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
22460 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
22470 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
22480 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
22490 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
224a0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
224b0 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
224c0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
224d0 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
224e0 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
224f0 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
22500 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
22510 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
22520 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22530 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
22540 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
22550 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
22560 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
22570 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
22580 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
22590 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
225a0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
225b0 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
225c0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
225d0 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
225e0 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
225f0 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
22600 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
22610 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
22620 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
22630 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
22640 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
22650 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
22660 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
22670 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
22680 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
22690 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
226a0 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
226b0 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
226c0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
226d0 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
226e0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
226f0 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
22700 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
22710 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
22720 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
22730 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
22740 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
22750 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
22760 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
22770 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
22780 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
22790 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
227a0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
227b0 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
227c0 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
227d0 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
227e0 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
227f0 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
22800 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
22810 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
22820 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
22830 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
22840 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
22850 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
22860 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
22870 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
22880 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
22890 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
228a0 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
228b0 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
228c0 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
228d0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
228e0 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
228f0 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
22900 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
22910 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
22920 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
22930 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
22940 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
22950 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
22960 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
22970 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
22980 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
22990 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
229a0 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
229b0 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
229c0 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
229d0 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
229e0 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
229f0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
22a00 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
22a10 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
22a20 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
22a30 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
22a40 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
22a50 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
22a60 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
22a70 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
22a80 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
22a90 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
22aa0 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
22ab0 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
22ac0 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
22ad0 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
22ae0 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
22af0 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
22b00 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
22b10 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a   (e.g. "C:")..**
22b20 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71  .** [[core URI q
22b30 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d  uery parameters]
22b40 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63  ].** The query c
22b50 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
22b60 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61  I may contain pa
22b70 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
22b80 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a  e interpreted.**
22b90 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74   either by SQLit
22ba0 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20  e itself, or by 
22bb0 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20  a [VFS | custom 
22bc0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
22bd0 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  on]..** SQLite i
22be0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 66 6f  nterprets the fo
22bf0 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75  llowing three qu
22c00 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
22c10 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
22c20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
22c30 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
22c40 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
22c50 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
22c60 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
22c70 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
22c80 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
22c90 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
22ca0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
22cb0 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
22cc0 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
22cd0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22ce0 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
22cf0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
22d00 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
22d10 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
22d20 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
22d30 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
22d40 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
22d50 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
22d60 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
22d70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
22d80 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
22d90 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
22da0 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
22db0 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
22dc0 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
22dd0 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
22de0 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
22df0 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
22e00 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
22e10 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
22e20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
22e30 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
22e40 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
22e50 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
22e60 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
22e70 65 72 20 22 72 6f 22 2c 20 22 72 77 22 20 6f 72  er "ro", "rw" or
22e80 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2e 20 41  .**     "rwc". A
22e90 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
22ea0 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
22eb0 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 72 72   value is an err
22ec0 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
22ed0 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
22ee0 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
22ef0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
22f00 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
22f10 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
22f20 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
22f30 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
22f40 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
22f50 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
22f60 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
22f70 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
22f80 70 72 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49  prepare_v2(). ^I
22f90 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
22fa0 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
22fb0 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
22fc0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
22fd0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
22fe0 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
22ff0 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
23000 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
23010 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
23020 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
23030 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
23040 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
23050 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
23060 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
23070 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
23080 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
23090 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
230a0 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
230b0 45 41 54 45 2e 20 5e 49 66 20 73 71 6c 69 74 65  EATE. ^If sqlite
230c0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 0a  3_open_v2() is .
230d0 2a 2a 20 20 20 20 20 75 73 65 64 2c 20 69 74 20  **     used, it 
230e0 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
230f0 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
23100 6f 72 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61  or the mode para
23110 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 0a 2a  meter that is .*
23120 2a 20 20 20 20 20 6c 65 73 73 20 72 65 73 74 72  *     less restr
23130 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74  ictive than that
23140 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
23150 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 61  e flags passed a
23160 73 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20  s the third .** 
23170 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a      parameter..*
23180 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
23190 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
231a0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
231b0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
231c0 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
231d0 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
231e0 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
231f0 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
23200 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
23210 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
23220 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
23230 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
23240 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
23250 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
23260 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23270 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
23280 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
23290 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
232a0 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
232b0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
232c0 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
232d0 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
232e0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
232f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
23300 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
23310 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
23320 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
23330 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
23340 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
23350 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
23360 61 76 69 6f 75 72 20 72 65 71 75 65 73 74 65 64  aviour requested
23370 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
23380 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
23390 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
233a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
233b0 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20  DCACHE flag..** 
233c0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
233d0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
233e0 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
233f0 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
23400 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
23410 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
23420 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
23430 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
23440 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
23450 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
23460 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
23470 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
23480 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
23490 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
234a0 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
234b0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
234c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
234d0 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
234e0 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
234f0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
23500 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
23510 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
23520 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
23530 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
23540 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
23550 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
23560 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23570 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
23580 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
23590 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
235a0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
235b0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
235c0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
235d0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
235e0 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
235f0 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
23600 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
23610 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
23620 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
23630 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
23640 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
23650 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
23660 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
23670 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23680 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
23690 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
236a0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
236b0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
236c0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
236d0 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
236e0 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
236f0 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
23700 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
23710 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
23720 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
23730 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
23740 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
23750 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
23760 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
23770 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
23780 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
23790 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
237a0 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
237b0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
237c0 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
237d0 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
237e0 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
237f0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
23800 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
23810 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
23820 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
23830 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
23840 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
23850 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
23860 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
23870 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
23880 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
23890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
238a0 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
238b0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
238c0 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
238d0 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
238e0 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
238f0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
23900 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
23910 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
23920 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
23930 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
23940 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
23950 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
23960 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
23970 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
23980 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20  nolock <td>.**  
23990 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
239a0 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
239b0 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
239c0 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
239d0 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74  x-nolock"..** <t
239e0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
239f0 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
23a00 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
23a10 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
23a20 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
23a30 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
23a40 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
23a50 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
23a60 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
23a70 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
23a80 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
23a90 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
23aa0 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
23ab0 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
23ac0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
23ad0 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
23ae0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
23af0 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
23b00 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
23b10 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
23b20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
23b30 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
23b40 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
23b50 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
23b60 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
23b70 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
23b80 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
23b90 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
23ba0 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
23bb0 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
23bc0 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
23bd0 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
23be0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
23bf0 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
23c00 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
23c10 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
23c20 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
23c30 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
23c40 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
23c50 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
23c60 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
23c70 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
23c80 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
23c90 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
23ca0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
23cb0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
23cc0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
23cd0 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
23ce0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
23cf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23d00 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
23d10 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
23d20 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
23d30 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
23d40 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
23d50 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
23d60 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
23d70 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
23d80 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
23d90 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
23da0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
23db0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
23dc0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
23dd0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
23de0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
23df0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
23e00 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
23e10 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
23e20 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
23e30 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
23e40 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
23e50 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
23e60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
23e70 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
23e80 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
23e90 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
23ea0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
23eb0 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
23ec0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
23ed0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
23ee0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
23ef0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
23f00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
23f10 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
23f20 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
23f30 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
23f40 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
23f50 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
23f60 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
23f70 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
23f80 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
23f90 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
23fa0 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
23fb0 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
23fc0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
23fd0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
23fe0 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
23ff0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
24000 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
24010 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
24020 20 54 68 69 73 20 69 73 20 61 20 75 74 69 6c 69   This is a utili
24030 74 79 20 72 6f 75 74 69 6e 65 2c 20 75 73 65 66  ty routine, usef
24040 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
24050 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
24060 63 68 65 63 6b 73 0a 2a 2a 20 74 6f 20 73 65 65  checks.** to see
24070 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
24080 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
24090 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
240a0 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
240b0 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
240c0 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
240d0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
240e0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
240f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 46 69 6c 65  .**.** The zFile
24100 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
24110 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f   the filename po
24120 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
24130 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
24140 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 56 46 53   method of a VFS
24150 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
24160 20 20 54 68 65 20 7a 50 61 72 61 6d 20 61 72 67    The zParam arg
24170 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 61 6d  ument is the nam
24180 65 20 6f 66 20 74 68 65 0a 2a 2a 20 71 75 65 72  e of the.** quer
24190 79 20 70 61 72 61 6d 65 74 65 72 20 77 65 20 73  y parameter we s
241a0 65 65 6b 2e 20 20 54 68 69 73 20 72 6f 75 74 69  eek.  This routi
241b0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  ne returns the v
241c0 61 6c 75 65 20 6f 66 20 74 68 65 20 7a 50 61 72  alue of the zPar
241d0 61 6d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  am.** parameter 
241e0 69 66 20 69 74 20 65 78 69 73 74 73 2e 20 20 49  if it exists.  I
241f0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
24200 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2c 20  does not exist, 
24210 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
24220 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
24230 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ointer..**.** If
24240 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 61   the zFilename a
24250 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
24260 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  function is not 
24270 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  a pointer that S
24280 51 4c 69 74 65 0a 2a 2a 20 70 61 73 73 65 64 20  QLite.** passed 
24290 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 56  into the xOpen V
242a0 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
242b0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
242c0 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
242d0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
242e0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
242f0 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  rable..*/.SQLITE
24300 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
24310 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
24320 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
24330 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
24340 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
24350 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
24360 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
24370 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
24380 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24390 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72  _errcode() inter
243a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
243b0 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
243c0 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
243d0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
243e0 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
243f0 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73   recent failed s
24400 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
24410 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  l.** associated 
24420 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
24430 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66   connection]. If
24440 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
24450 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20  l failed.** but 
24460 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
24470 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
24480 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
24490 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  alue from.** sql
244a0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
244b0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54  s undefined.  ^T
244c0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
244d0 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
244e0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
244f0 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
24500 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
24510 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
24520 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
24530 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
24540 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
24550 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
24560 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
24570 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
24580 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
24590 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
245a0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
245b0 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
245c0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
245d0 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
245e0 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
245f0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
24600 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
24610 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
24620 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
24630 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
24640 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
24650 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
24660 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
24670 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
24680 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
24690 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
246a0 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
246b0 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
246c0 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
246d0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
246e0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
246f0 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
24700 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
24710 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
24720 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
24730 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
24740 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
24750 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
24760 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
24770 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
24780 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
24790 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
247a0 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
247b0 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
247c0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
247d0 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
247e0 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
247f0 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
24800 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
24810 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
24820 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
24830 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
24840 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
24850 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
24860 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
24870 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
24880 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
24890 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
248a0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
248b0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
248c0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
248d0 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
248e0 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
248f0 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
24900 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
24910 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
24920 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
24930 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
24940 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
24950 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
24960 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
24970 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
24980 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
24990 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
249a0 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
249b0 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
249c0 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
249d0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
249e0 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
249f0 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
24a00 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
24a10 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
24a20 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49   be set..*/.SQLI
24a30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
24a40 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
24a50 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
24a60 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
24a70 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
24a80 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53  (sqlite3 *db);.S
24a90 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
24aa0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
24ab0 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
24ac0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
24ad0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
24ae0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
24af0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24b00 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e  EF: SQL Statemen
24b10 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
24b20 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
24b30 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
24b40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
24b50 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
24b60 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
24b70 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
24b80 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
24b90 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ent..** This obj
24ba0 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79  ect is variously
24bb0 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65   known as a "pre
24bc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22  pared statement"
24bd0 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c   or a.** "compil
24be0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
24bf0 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61  " or simply as a
24c00 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a   "statement"..**
24c10 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20  .** The life of 
24c20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  a statement obje
24c30 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e  ct goes somethin
24c40 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  g like this:.**.
24c50 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
24c60 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63  Create the objec
24c70 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
24c80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
24c90 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20  r a related.**  
24ca0 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a      function..**
24cb0 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
24cc0 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d  s to [host param
24cd0 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
24ce0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
24cf0 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
24d00 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
24d10 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
24d20 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
24d30 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
24d40 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
24d50 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65   Reset the state
24d60 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
24d70 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
24d80 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
24d90 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
24da0 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
24db0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
24dc0 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
24dd0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
24de0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
24df0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
24e00 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e  Refer to documen
24e10 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  tation on indivi
24e20 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f  dual methods abo
24e30 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ve for additiona
24e40 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
24e50 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
24e60 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
24e70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
24e80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24e90 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
24ea0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
24eb0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
24ec0 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
24ed0 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
24ee0 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
24ef0 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
24f00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
24f10 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
24f20 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
24f30 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
24f40 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
24f50 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
24f60 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
24f70 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
24f80 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
24f90 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
24fa0 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
24fb0 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
24fc0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
24fd0 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
24fe0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
24ff0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
25000 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
25010 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
25020 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
25030 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
25040 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
25050 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
25060 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
25070 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
25080 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
25090 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
250a0 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
250b0 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
250c0 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
250d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
250e0 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
250f0 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
25100 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
25110 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
25120 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
25130 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
25140 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
25150 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
25160 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
25170 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
25180 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
25190 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
251a0 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
251b0 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
251c0 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
251d0 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
251e0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
251f0 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
25200 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
25210 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
25220 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
25230 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
25240 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
25250 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
25260 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
25270 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
25280 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
25290 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
252a0 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
252b0 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
252c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
252d0 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
252e0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
252f0 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
25300 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
25310 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
25320 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
25330 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
25340 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
25350 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
25360 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
25370 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
25380 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
25390 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
253a0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
253b0 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
253c0 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
253d0 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
253e0 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
253f0 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
25400 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
25410 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
25420 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
25430 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
25440 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
25450 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
25460 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
25470 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
25480 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
25490 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
254a0 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
254b0 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
254c0 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
254d0 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
254e0 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
254f0 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
25500 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
25510 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
25520 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
25530 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
25540 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
25550 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
25560 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
25570 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
25580 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
25590 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
255a0 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
255b0 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
255c0 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
255d0 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
255e0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
255f0 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
25600 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
25610 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
25620 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
25630 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c  releases..*/.SQL
25640 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
25650 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
25660 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
25670 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
25680 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
25690 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
256a0 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
256b0 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
256c0 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
256d0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
256e0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
256f0 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
25700 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
25710 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
25720 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
25730 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25740 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
25750 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
25760 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
25770 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
25780 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
25790 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
257a0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
257b0 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
257c0 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
257d0 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
257e0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
257f0 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
25800 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25810 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
25820 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
25830 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
25840 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
25850 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
25860 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
25870 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
25880 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
25890 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
258a0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
258b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
258c0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
258d0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
258e0 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
258f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25900 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
25910 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
25920 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
25930 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25940 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
25950 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
25960 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
25970 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
25980 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
25990 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
259a0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
259b0 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
259c0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
259d0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
259e0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
259f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
25a00 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
25a10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
25a20 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
25a30 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25a40 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
25a50 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
25a60 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
25a70 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25a80 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
25a90 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
25aa0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
25ab0 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
25ac0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25ad0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
25ae0 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
25af0 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
25b00 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
25b10 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25b20 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
25b30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
25b40 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
25b50 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25b60 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
25b70 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
25b80 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
25b90 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
25ba0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
25bb0 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
25bc0 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
25bd0 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
25be0 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
25bf0 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
25c00 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
25c10 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
25c20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25c30 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
25c40 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
25c50 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25c60 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
25c70 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25c80 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
25c90 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
25ca0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
25cb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25cc0 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
25cd0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25ce0 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
25cf0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25d00 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
25d10 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
25d20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
25d30 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
25d40 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
25d50 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
25d60 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25d70 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
25d80 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
25d90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25da0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
25db0 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
25dc0 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
25dd0 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
25de0 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
25df0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25e00 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
25e10 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
25e20 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
25e30 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
25e40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25e50 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
25e60 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
25e70 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
25e80 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
25e90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
25ea0 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
25eb0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25ec0 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
25ed0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25ee0 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
25ef0 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
25f00 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
25f10 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
25f20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
25f30 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
25f40 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
25f50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25f60 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
25f70 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
25f80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25f90 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
25fa0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
25fb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25fc0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
25fd0 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
25fe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25ff0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
26000 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
26010 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26020 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
26030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
26040 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26050 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
26060 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
26070 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26080 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
26090 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
260a0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
260b0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
260c0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
260d0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
260e0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
260f0 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
26100 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
26110 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
26120 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
26130 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
26140 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
26150 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
26160 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
26170 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
26180 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
26190 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
261a0 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
261b0 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
261c0 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
261d0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
261e0 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
261f0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
26200 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
26210 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
26220 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26230 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
26240 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
26250 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
26260 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
26270 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
26280 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
26290 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
262a0 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
262b0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
262c0 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
262d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
262e0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
262f0 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
26300 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
26310 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
26320 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
26330 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
26340 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
26350 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
26360 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
26370 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
26380 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
26390 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
263a0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
263b0 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
263c0 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
263d0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
263e0 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
263f0 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
26400 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
26410 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
26420 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
26430 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
26440 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
26450 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
26460 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
26470 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
26480 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
26490 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
264a0 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
264b0 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
264c0 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
264d0 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
264e0 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
264f0 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
26500 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
26510 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
26520 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
26530 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
26540 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
26550 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
26560 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
26570 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
26580 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
26590 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
265a0 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
265b0 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
265c0 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
265d0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
265e0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
265f0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
26600 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
26610 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
26620 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  s..**.** ^If pzT
26630 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
26640 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
26650 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
26660 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
26670 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
26680 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
26690 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
266a0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
266b0 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
266c0 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
266d0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
266e0 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
266f0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
26700 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
26710 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
26720 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
26730 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
26740 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
26750 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
26760 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
26770 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
26780 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
26790 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
267a0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
267b0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
267c0 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
267d0 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
267e0 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
267f0 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
26800 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
26810 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
26820 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
26830 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
26840 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
26850 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
26860 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
26870 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
26880 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
26890 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
268a0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
268b0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
268c0 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
268d0 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
268e0 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
268f0 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
26900 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
26910 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
26920 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
26930 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
26940 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
26950 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
26960 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26970 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
26980 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
26990 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
269a0 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
269b0 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
269c0 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
269d0 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
269e0 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
269f0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
26a00 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
26a10 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
26a20 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
26a30 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
26a40 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
26a50 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
26a60 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
26a70 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
26a80 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
26a90 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
26aa0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
26ab0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
26ac0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
26ad0 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
26ae0 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
26af0 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
26b00 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
26b10 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
26b20 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
26b30 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
26b40 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
26b50 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
26b60 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
26b70 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
26b80 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
26b90 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
26ba0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
26bb0 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
26bc0 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
26bd0 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a  o run it again..
26be0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
26bf0 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
26c00 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
26c10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
26c20 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
26c30 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
26c40 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
26c50 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
26c60 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
26c70 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
26c80 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
26c90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
26ca0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
26cb0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
26cc0 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
26cd0 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
26ce0 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
26cf0 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
26d00 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
26d10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
26d20 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
26d30 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
26d40 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
26d50 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
26d60 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
26d70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
26d80 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
26d90 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
26da0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
26db0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
26dc0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
26dd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
26de0 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
26df0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
26e00 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
26e10 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
26e20 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
26e30 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
26e40 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
26e50 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
26e60 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
26e70 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
26e80 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
26e90 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
26ea0 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
26eb0 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
26ec0 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
26ed0 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
26ee0 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
26ef0 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
26f00 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
26f10 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
26f20 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
26f30 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
26f40 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
26f50 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
26f60 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
26f70 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
26f80 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
26f90 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
26fa0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
26fb0 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
26fc0 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
26fd0 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
26fe0 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
26ff0 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
27000 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
27010 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
27020 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
27030 41 42 4c 45 5f 53 54 41 54 32 5d 20 63 6f 6d 70  ABLE_STAT2] comp
27040 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
27050 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74  is enabled..** t
27060 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  he .** </li>.** 
27070 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ol>.*/.SQLITE_
27080 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
27090 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
270a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
270b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
270c0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
270d0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
270e0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
270f0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
27100 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
27110 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
27120 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
27130 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
27140 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
27150 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
27160 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
27170 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
27180 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
27190 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
271a0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
271b0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
271c0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
271d0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
271e0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
271f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
27200 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
27210 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27220 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
27230 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
27240 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
27250 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
27260 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
27270 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
27280 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
27290 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
272a0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
272b0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
272c0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
272d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
272e0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
272f0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
27300 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
27310 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
27320 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
27330 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
27340 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
27350 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
27360 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27370 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
27380 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
27390 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
273a0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
273b0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
273c0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
273d0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
273e0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
273f0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
27400 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
27410 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
27420 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
27430 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
27440 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
27450 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
27460 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
27470 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
27480 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
27490 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
274a0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
274b0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
274c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
274d0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
274e0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
274f0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
27500 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
27510 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
27520 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
27530 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
27540 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
27550 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
27560 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
27570 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
27580 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
27590 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
275a0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
275b0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
275c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
275d0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
275e0 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
275f0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
27600 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
27610 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
27620 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
27630 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
27640 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
27650 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27660 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
27670 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
27680 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
27690 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
276a0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
276b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
276c0 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  v2()]..*/.SQLITE
276d0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
276e0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
276f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
27700 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27710 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
27720 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
27730 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
27740 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
27750 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
27760 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
27770 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
27780 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
27790 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
277a0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
277b0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
277c0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
277d0 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
277e0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
277f0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
27800 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
27810 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
27820 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
27830 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
27840 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
27850 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
27860 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
27870 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
27880 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
27890 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
278a0 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
278b0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
278c0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
278d0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
278e0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
278f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
27900 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
27910 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27920 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
27930 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
27940 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
27950 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
27960 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
27970 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
27980 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
27990 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
279a0 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
279b0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
279c0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
279d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
279e0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
279f0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
27a00 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
27a10 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
27a20 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
27a30 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
27a40 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
27a50 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
27a60 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
27a70 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
27a80 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
27a90 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
27aa0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
27ab0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
27ac0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
27ad0 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
27ae0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
27af0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
27b00 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
27b10 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
27b20 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
27b30 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
27b40 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
27b50 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
27b60 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
27b70 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
27b80 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
27b90 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
27ba0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
27bb0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
27bc0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
27bd0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
27be0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
27bf0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
27c00 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
27c10 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
27c20 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
27c30 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
27c40 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
27c50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
27c60 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
27c70 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
27c80 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
27c90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27ca0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
27cb0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
27cc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
27cd0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27ce0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
27cf0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27d00 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
27d10 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
27d20 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
27d30 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
27d40 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
27d50 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
27d60 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
27d70 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
27d80 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
27d90 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
27da0 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
27db0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
27dc0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
27dd0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
27de0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
27df0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
27e00 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
27e10 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
27e20 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27e30 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
27e40 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
27e50 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
27e60 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
27e70 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
27e80 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27e90 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
27ea0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
27eb0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
27ec0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
27ed0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
27ee0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
27ef0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
27f00 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
27f10 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
27f20 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
27f30 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
27f40 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
27f50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27f60 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
27f70 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
27f80 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
27f90 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
27fa0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
27fb0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
27fc0 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
27fd0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
27fe0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
27ff0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28000 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
28010 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
28020 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
28030 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28040 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
28050 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
28060 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
28070 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
28080 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
28090 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
280a0 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
280b0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
280c0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
280d0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
280e0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
280f0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
28100 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
28110 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
28120 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
28130 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
28140 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
28150 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
28160 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
28170 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
28180 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
28190 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
281a0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
281b0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
281c0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
281d0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
281e0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
281f0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
28200 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
28210 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
28220 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
28230 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
28240 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
28250 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
28260 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
28270 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
28280 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
28290 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
282a0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
282b0 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
282c0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
282d0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
282e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
282f0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
28300 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
28310 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
28320 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
28330 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
28340 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
28350 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
28360 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
28370 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28380 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
28390 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
283a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
283b0 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
283c0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
283d0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
283e0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
283f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
28400 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
28410 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
28420 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
28430 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28440 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
28450 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
28460 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
28470 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
28480 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
28490 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
284a0 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
284b0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
284c0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
284d0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
284e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
284f0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
28500 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
28510 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
28520 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
28530 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
28540 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
28550 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
28560 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
28570 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28580 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
28590 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
285a0 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
285b0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
285c0 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
285d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
285e0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
285f0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
28600 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
28610 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
28620 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
28630 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
28640 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
28650 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
28660 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
28670 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
28680 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
28690 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
286a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
286b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
286c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
286d0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
286e0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
286f0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
28700 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
28710 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
28720 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
28730 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
28740 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
28750 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
28760 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
28770 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
28780 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
28790 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
287a0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
287b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
287c0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
287d0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
287e0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
287f0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
28800 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
28810 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
28820 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
28830 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
28840 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
28850 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
28860 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
28870 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
28880 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
28890 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
288a0 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
288b0 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
288c0 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
288d0 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
288e0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
288f0 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
28900 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
28910 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
28920 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
28930 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
28940 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
28950 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
28960 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
28970 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
28980 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
28990 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
289a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
289b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
289c0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
289d0 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
289e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
289f0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
28a00 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
28a10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
28a20 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
28a30 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
28a40 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
28a50 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
28a60 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
28a70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
28a80 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
28a90 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
28aa0 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
28ab0 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
28ac0 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
28ad0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
28ae0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
28af0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
28b00 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
28b10 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
28b20 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
28b30 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
28b40 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
28b50 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
28b60 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
28b70 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
28b80 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
28b90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28ba0 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
28bb0 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
28bc0 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
28bd0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
28be0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
28bf0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
28c00 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
28c10 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
28c20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
28c30 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
28c40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
28c50 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
28c60 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
28c70 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
28c80 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
28c90 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
28ca0 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
28cb0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  er..**.** ^(In t
28cc0 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
28cd0 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
28ce0 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
28cf0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
28d00 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
28d10 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
28d20 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
28d30 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
28d40 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
28d50 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
28d60 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
28d70 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
28d80 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
28d90 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
28da0 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ter is negative,
28db0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
28dc0 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
28dd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
28de0 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
28df0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
28e00 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tor..**.** ^The 
28e10 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
28e20 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
28e30 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
28e40 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
28e50 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
28e60 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
28e70 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
28e80 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
28e90 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
28ea0 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
28eb0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
28ec0 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
28ed0 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
28ee0 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
28ef0 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
28f00 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
28f10 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
28f20 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20  bind_blob(),.** 
28f30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28f40 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  t(), or sqlite3_
28f50 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61  bind_text16() fa
28f60 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68  ils.  .** ^If th
28f70 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
28f80 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
28f90 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
28fa0 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
28fb0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
28fc0 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
28fd0 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
28fe0 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
28ff0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
29000 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
29010 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
29020 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
29030 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
29040 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
29050 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
29060 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
29070 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
29080 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
29090 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
290a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
290b0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
290c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
290d0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
290e0 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
290f0 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
29100 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
29110 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
29120 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
29130 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
29140 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
29150 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
29160 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
29170 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
29180 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
29190 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
291a0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
291b0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
291c0 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
291d0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
291e0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
291f0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
29200 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
29210 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
29220 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
29230 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
29240 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
29250 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
29260 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
29270 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
29280 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
29290 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
292a0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
292b0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
292c0 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
292d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
292e0 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
292f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29300 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
29310 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
29320 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
29330 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
29340 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29350 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
29360 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
29370 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
29380 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
29390 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
293a0 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
293b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
293c0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
293d0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
293e0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
293f0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
29400 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
29410 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
29420 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
29430 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
29440 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
29450 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
29460 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
29470 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
29480 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29490 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
294a0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
294b0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
294c0 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
294d0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
294e0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
294f0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
29500 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
29510 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
29520 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
29530 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
29540 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
29550 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
29560 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
29570 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29580 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29590 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
295a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
295b0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
295c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
295d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
295e0 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
295f0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29600 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
29610 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
29620 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
29630 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
29640 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
29650 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
29660 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
29670 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
29680 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  e);.SQLITE_API i
29690 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
296a0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
296b0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51  *, int, int);.SQ
296c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
296d0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
296e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
296f0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
29700 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  4);.SQLITE_API i
29710 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
29720 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
29730 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
29740 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29750 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
29760 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
29770 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
29780 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
29790 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
297a0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
297b0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
297c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
297d0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
297e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
297f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
29800 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
29810 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29820 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
29830 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
29840 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
29850 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
29860 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29870 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
29880 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
29890 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
298a0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
298b0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
298c0 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
298d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
298e0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
298f0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
29900 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
29910 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
29920 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
29930 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
29940 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
29950 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
29960 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
29970 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
29980 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
29990 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
299a0 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
299b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
299c0 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
299d0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
299e0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
299f0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
29a00 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
29a10 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
29a20 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
29a30 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
29a40 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
29a50 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
29a60 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
29a70 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
29a80 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
29a90 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
29aa0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
29ab0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
29ac0 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
29ad0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
29ae0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29af0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
29b00 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
29b10 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
29b20 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
29b30 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29b40 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
29b50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
29b60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
29b70 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
29b80 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
29b90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
29ba0 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
29bb0 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
29bc0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29bd0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
29be0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
29bf0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
29c00 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
29c10 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
29c20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29c30 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
29c40 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
29c50 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
29c60 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
29c70 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
29c80 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
29c90 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
29ca0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
29cb0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
29cc0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
29cd0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
29ce0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
29cf0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
29d00 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
29d10 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
29d20 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
29d30 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
29d40 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
29d50 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
29d60 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
29d70 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
29d80 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
29d90 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
29da0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
29db0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
29dc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
29dd0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
29de0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
29df0 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
29e00 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
29e10 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
29e20 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
29e30 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
29e40 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
29e50 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
29e60 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
29e70 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
29e80 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
29e90 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
29ea0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
29eb0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
29ec0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
29ed0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
29ee0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
29ef0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
29f00 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
29f10 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
29f20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
29f30 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
29f40 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
29f50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29f60 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
29f70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29f80 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
29f90 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
29fa0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
29fb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29fc0 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
29fd0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
29fe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
29ff0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
2a000 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
2a010 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
2a020 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
2a030 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
2a040 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
2a050 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
2a060 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2a070 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
2a080 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
2a090 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
2a0a0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
2a0b0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2a0c0 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
2a0d0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
2a0e0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
2a0f0 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
2a100 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
2a110 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
2a120 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
2a130 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
2a140 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
2a150 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
2a160 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
2a170 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
2a180 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2a190 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2a1a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2a1b0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2a1c0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2a1d0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2a1e0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
2a1f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a200 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2a210 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2a220 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a230 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2a240 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a250 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2a260 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
2a270 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
2a280 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
2a290 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2a2a0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
2a2b0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
2a2c0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
2a2d0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
2a2e0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
2a2f0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2a300 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
2a310 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2a320 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2a330 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
2a340 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
2a350 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
2a360 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45   NULL..*/.SQLITE
2a370 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2a380 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2a390 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2a3a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a3b0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
2a3c0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
2a3d0 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  et.**.** ^Return
2a3e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2a3f0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2a400 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
2a410 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
2a420 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a430 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
2a440 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
2a450 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
2a460 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
2a470 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
2a480 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
2a490 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
2a4a0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2a4b0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2a4c0 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
2a4d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2a4e0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
2a4f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2a500 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a510 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
2a520 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2a530 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2a540 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2a550 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
2a560 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
2a570 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
2a580 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
2a590 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2a5a0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
2a5b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2a5c0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2a5d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2a5e0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2a5f0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
2a600 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
2a610 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2a620 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2a630 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2a640 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
2a650 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2a660 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2a670 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
2a680 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
2a690 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2a6a0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2a6b0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
2a6c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2a6d0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
2a6e0 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
2a6f0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
2a700 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
2a710 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2a720 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
2a730 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
2a740 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2a750 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
2a760 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
2a770 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a780 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2a790 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2a7a0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2a7b0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2a7c0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2a7d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2a7e0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2a7f0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2a800 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2a810 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2a820 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
2a830 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2a840 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
2a850 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2a860 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
2a870 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
2a880 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
2a890 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
2a8a0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
2a8b0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
2a8c0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
2a8d0 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
2a8e0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
2a8f0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2a900 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2a910 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
2a920 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
2a930 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
2a940 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
2a950 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
2a960 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
2a970 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
2a980 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
2a990 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
2a9a0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
2a9b0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
2a9c0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
2a9d0 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
2a9e0 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
2a9f0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
2aa00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2aa10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2aa20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2aa30 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
2aa40 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2aa50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2aa60 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2aa70 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
2aa80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
2aa90 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
2aaa0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2aab0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2aac0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
2aad0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
2aae0 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
2aaf0 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
2ab00 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
2ab10 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
2ab20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
2ab30 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
2ab40 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2ab50 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
2ab60 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2ab70 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
2ab80 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
2ab90 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
2aba0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
2abb0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2abc0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
2abd0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
2abe0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
2abf0 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
2ac00 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2ac10 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
2ac20 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
2ac30 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2ac40 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
2ac50 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
2ac60 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
2ac70 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
2ac80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ac90 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
2aca0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2acb0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2acc0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2acd0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2ace0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2acf0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2ad00 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2ad10 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2ad20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2ad30 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
2ad40 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
2ad50 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
2ad60 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
2ad70 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
2ad80 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
2ad90 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
2ada0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
2adb0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
2adc0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
2add0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
2ade0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2adf0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2ae00 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
2ae10 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2ae20 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
2ae30 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2ae40 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2ae50 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
2ae60 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
2ae70 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
2ae80 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
2ae90 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
2aea0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
2aeb0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
2aec0 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
2aed0 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
2aee0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
2aef0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
2af00 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2af10 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
2af20 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
2af30 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
2af40 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
2af50 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
2af60 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
2af70 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
2af80 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
2af90 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
2afa0 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
2afb0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2afc0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
2afd0 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
2afe0 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
2aff0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2b000 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2b010 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
2b020 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
2b030 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
2b040 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
2b050 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
2b060 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
2b070 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
2b080 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
2b090 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
2b0a0 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
2b0b0 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
2b0c0 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
2b0d0 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
2b0e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
2b0f0 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
2b100 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2b110 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2b120 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2b130 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2b140 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2b150 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2b160 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
2b170 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2b180 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2b190 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
2b1a0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
2b1b0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
2b1c0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
2b1d0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
2b1e0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2b1f0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
2b200 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2b210 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2b220 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2b230 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
2b240 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2b250 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
2b260 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
2b270 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
2b280 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
2b290 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
2b2a0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
2b2b0 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
2b2c0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2b2d0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2b2e0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
2b2f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2b300 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2b310 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2b320 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2b330 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2b340 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2b350 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2b360 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2b370 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2b380 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2b390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2b3a0 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
2b3b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2b3c0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2b3d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2b3e0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
2b3f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2b400 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2b410 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2b420 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2b430 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2b440 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2b450 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2b460 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2b470 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2b480 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2b490 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b4a0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2b4b0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2b4c0 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
2b4d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2b4e0 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2b4f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2b500 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2b510 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2b520 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2b530 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2b540 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2b550 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2b560 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2b570 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2b580 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2b590 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2b5a0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2b5b0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2b5c0 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
2b5d0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
2b5e0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2b5f0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2b600 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
2b610 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2b620 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
2b630 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2b640 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
2b650 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2b660 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
2b670 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
2b680 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
2b690 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2b6a0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
2b6b0 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
2b6c0 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
2b6d0 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
2b6e0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
2b6f0 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
2b700 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
2b710 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
2b720 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2b730 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2b740 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2b750 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2b760 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2b770 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2b780 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2b790 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2b7a0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2b7b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2b7c0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2b7d0 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2b7e0 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2b7f0 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2b800 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2b810 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2b820 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2b830 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2b840 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2b850 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2b860 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2b870 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2b880 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2b890 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2b8a0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2b8b0 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2b8c0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2b8d0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2b8e0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2b8f0 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2b900 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2b910 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2b920 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2b930 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2b940 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2b950 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b960 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2b970 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2b980 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2b990 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
2b9a0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2b9b0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
2b9c0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
2b9d0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
2b9e0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2b9f0 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2ba00 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2ba10 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2ba20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2ba30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2ba40 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2ba50 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2ba60 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2ba70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ba80 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2ba90 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2baa0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2bab0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2bac0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2bad0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2bae0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2baf0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2bb00 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2bb10 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2bb20 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2bb30 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2bb40 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2bb50 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2bb60 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2bb70 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2bb80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2bb90 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2bba0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2bbb0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2bbc0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2bbd0 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2bbe0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2bbf0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2bc00 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2bc10 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2bc20 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2bc30 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2bc40 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2bc50 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2bc60 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2bc70 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2bc80 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2bc90 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2bca0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2bcb0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2bcc0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2bcd0 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2bce0 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2bcf0 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2bd00 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2bd10 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2bd20 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2bd30 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2bd40 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2bd50 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2bd60 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2bd70 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2bd80 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2bd90 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2bda0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2bdb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2bdc0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2bdd0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2bde0 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2bdf0 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2be00 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2be10 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2be20 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2be30 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2be40 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2be50 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2be60 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2be70 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2be80 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2be90 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2bea0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2beb0 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2bec0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2bed0 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2bee0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2bef0 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2bf00 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2bf10 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2bf20 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2bf30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2bf40 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2bf50 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2bf60 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2bf70 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2bf80 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2bf90 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2bfa0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2bfb0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2bfc0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2bfd0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2bfe0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2bff0 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2c000 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2c010 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2c020 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2c030 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2c040 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2c050 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2c060 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2c070 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2c080 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2c090 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2c0a0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2c0b0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2c0c0 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2c0d0 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2c0e0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2c0f0 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2c100 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2c110 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2c120 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2c130 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2c140 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2c150 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2c160 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2c170 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2c180 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2c190 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2c1a0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2c1b0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2c1c0 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2c1d0 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2c1e0 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2c1f0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2c200 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2c210 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2c220 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2c230 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2c240 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2c250 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2c260 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2c270 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2c280 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2c290 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2c2a0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2c2b0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2c2c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c2d0 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2c2e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2c2f0 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2c300 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2c310 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2c320 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2c330 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2c340 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2c350 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2c360 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2c370 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2c380 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2c390 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2c3a0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2c3b0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2c3c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c3d0 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2c3e0 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2c3f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2c400 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2c410 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2c420 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2c430 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2c440 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2c450 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2c460 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2c470 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2c480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c490 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2c4a0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2c4b0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2c4c0 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2c4d0 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2c4e0 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2c4f0 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2c500 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2c510 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2c520 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2c530 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2c540 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2c550 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2c560 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2c570 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2c580 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2c590 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2c5a0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2c5b0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2c5c0 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2c5d0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2c5e0 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2c5f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c600 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2c610 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2c620 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2c630 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2c640 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2c650 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2c660 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2c670 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2c680 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2c690 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2c6a0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2c6b0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2c6c0 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2c6d0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2c6e0 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2c6f0 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2c700 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2c710 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2c720 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2c730 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2c740 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2c750 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2c760 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2c770 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2c780 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2c790 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2c7a0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2c7b0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2c7c0 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2c7d0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2c7e0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2c7f0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2c800 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2c810 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2c820 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2c830 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2c840 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2c850 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2c860 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2c870 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2c880 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2c890 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2c8a0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2c8b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c8c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2c8d0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2c8e0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2c8f0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2c900 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2c910 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2c920 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2c930 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2c940 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2c950 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2c960 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2c970 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2c980 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2c990 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
2c9a0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
2c9b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2c9c0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
2c9d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c9e0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2c9f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2ca00 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
2ca10 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
2ca20 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2ca30 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2ca40 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
2ca50 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
2ca60 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
2ca70 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
2ca80 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2ca90 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
2caa0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
2cab0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
2cac0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2cad0 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ended..*/.SQLITE
2cae0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2caf0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
2cb00 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2cb10 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
2cb20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
2cb30 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
2cb40 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2cb50 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
2cb60 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2cb70 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2cb80 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
2cb90 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2cba0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
2cbb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cbc0 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
2cbd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
2cbe0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
2cbf0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
2cc00 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
2cc10 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
2cc20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
2cc30 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
2cc40 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
2cc50 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
2cc60 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2cc70 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
2cc80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2cc90 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2cca0 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
2ccb0 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
2ccc0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
2ccd0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2cce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2ccf0 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()].*/.SQLITE_AP
2cd00 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  I int sqlite3_da
2cd10 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
2cd20 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2cd30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cd40 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
2cd50 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
2cd60 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
2cd70 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
2cd80 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
2cd90 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
2cda0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
2cdb0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2cdc0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
2cdd0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2cde0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
2cdf0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2ce00 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
2ce10 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
2ce20 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
2ce30 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
2ce40 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2ce50 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
2ce60 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
2ce70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
2ce80 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
2ce90 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
2cea0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
2ceb0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
2cec0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
2ced0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
2cee0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
2cef0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
2cf00 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
2cf10 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
2cf20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2cf30 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
2cf40 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
2cf50 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
2cf60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2cf70 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
2cf80 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
2cf90 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2cfa0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
2cfb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
2cfc0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
2cfd0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
2cfe0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2cff0 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
2d000 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
2d010 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
2d020 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
2d030 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
2d040 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
2d050 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
2d060 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
2d070 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2d080 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
2d090 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
2d0a0 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22  the "result set"
2d0b0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2d0c0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2d0d0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2d0e0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
2d0f0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
2d100 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
2d110 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
2d120 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
2d130 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
2d140 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
2d150 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
2d160 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d170 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
2d180 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
2d190 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
2d1a0 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
2d1b0 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
2d1c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2d1d0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
2d1e0 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
2d1f0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2d200 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2d210 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
2d220 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
2d230 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
2d240 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
2d250 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2d260 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2d270 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
2d280 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
2d290 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2d2a0 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
2d2b0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
2d2c0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2d2d0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
2d2e0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
2d2f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
2d300 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
2d310 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
2d320 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
2d330 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
2d340 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
2d350 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
2d360 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
2d370 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
2d380 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
2d390 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
2d3a0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2d3b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2d3c0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
2d3d0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
2d3e0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2d3f0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
2d400 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d410 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
2d420 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
2d430 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
2d440 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2d450 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
2d460 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d470 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2d480 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
2d490 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
2d4a0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2d4b0 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
2d4c0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2d4d0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
2d4e0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2d4f0 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
2d500 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2d510 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d520 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2d530 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
2d540 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
2d550 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
2d560 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
2d570 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
2d580 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
2d590 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2d5a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2d5b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2d5c0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
2d5d0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
2d5e0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
2d5f0 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
2d600 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
2d610 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
2d620 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
2d630 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
2d640 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
2d650 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
2d660 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
2d670 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
2d680 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
2d690 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
2d6a0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
2d6b0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
2d6c0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2d6d0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
2d6e0 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
2d6f0 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
2d700 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
2d710 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
2d720 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
2d730 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2d740 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
2d750 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2d760 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2d770 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
2d780 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
2d790 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
2d7a0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
2d7b0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
2d7c0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
2d7d0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
2d7e0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
2d7f0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2d800 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2d810 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
2d820 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2d830 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
2d840 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2d850 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d860 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2d870 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2d880 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2d890 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2d8a0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2d8b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
2d8c0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2d8d0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
2d8e0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2d8f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2d900 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2d910 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2d920 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2d930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d940 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
2d950 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2d960 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2d970 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2d980 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
2d990 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2d9a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2d9b0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2d9c0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2d9d0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2d9e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d9f0 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
2da00 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
2da10 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2da20 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
2da30 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2da40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2da50 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
2da60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2da70 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2da80 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2da90 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2daa0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
2dab0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2dac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2dad0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
2dae0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2daf0 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
2db00 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2db10 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2db20 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2db30 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2db40 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2db50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2db60 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2db70 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2db80 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2db90 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
2dba0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2dbb0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2dbc0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2dbd0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2dbe0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2dbf0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2dc00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2dc10 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2dc20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
2dc30 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
2dc40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2dc50 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
2dc60 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2dc70 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
2dc80 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
2dc90 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
2dca0 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
2dcb0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
2dcc0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
2dcd0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2dce0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2dcf0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2dd00 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
2dd10 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
2dd20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
2dd30 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
2dd40 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
2dd50 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2dd60 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
2dd70 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
2dd80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2dd90 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
2dda0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2ddb0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
2ddc0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
2ddd0 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ways zero termin
2dde0 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
2ddf0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
2de00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2de10 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
2de20 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
2de30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2de40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65  .**.** ^The obje
2de50 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
2de60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2de70 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
2de80 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2de90 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2dea0 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
2deb0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2dec0 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
2ded0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2dee0 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
2def0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
2df00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2df10 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
2df20 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
2df30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2df40 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2df50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2df60 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2df70 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
2df80 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
2df90 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
2dfa0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2dfb0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
2dfc0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2dfd0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2dfe0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2dff0 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
2e000 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2e010 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
2e020 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
2e030 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
2e040 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
2e050 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
2e060 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
2e070 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
2e080 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
2e090 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
2e0a0 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
2e0b0 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
2e0c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2e0d0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
2e0e0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
2e0f0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
2e100 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2e110 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
2e120 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
2e130 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
2e140 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
2e150 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
2e160 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
2e170 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
2e180 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
2e190 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
2e1a0 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
2e1b0 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
2e1c0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
2e1d0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
2e1e0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
2e1f0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
2e200 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2e210 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2e220 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
2e230 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2e240 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
2e250 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2e260 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
2e270 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2e280 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
2e290 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2e2a0 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
2e2b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2e2c0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
2e2d0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
2e2e0 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
2e2f0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2e300 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2e310 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2e320 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2e330 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
2e340 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2e350 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
2e360 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
2e370 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
2e380 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2e390 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2e3a0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
2e3b0 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74  rom float to int
2e3c0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
2e3d0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2e3e0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2e3f0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2e400 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
2e410 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2e420 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2e430 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41  td> Same as FLOA
2e440 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  T->TEXT.** <tr><
2e450 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2e460 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2e470 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   Use atoi().** <
2e480 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2e490 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2e4a0 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a  <td> Use atof().
2e4b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2e4c0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
2e4d0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
2e4e0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
2e4f0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
2e500 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
2e510 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
2e520 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   use atoi().** <
2e530 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2e540 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2e550 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
2e560 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
2e570 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
2e580 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2e590 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
2e5a0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
2e5b0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
2e5c0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
2e5d0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
2e5e0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
2e5f0 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
2e600 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
2e610 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
2e620 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
2e630 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
2e640 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
2e650 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
2e660 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
2e670 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
2e680 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
2e690 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
2e6a0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
2e6b0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
2e6c0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
2e6d0 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
2e6e0 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
2e6f0 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
2e700 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
2e710 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2e720 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
2e730 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
2e740 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2e750 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
2e760 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2e770 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
2e780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e790 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
2e7a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e7b0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
2e7c0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
2e7d0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
2e7e0 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
2e7f0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
2e800 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
2e810 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
2e820 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2e830 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2e840 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
2e850 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2e860 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
2e870 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2e880 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2e890 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
2e8a0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
2e8b0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
2e8c0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
2e8d0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
2e8e0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
2e8f0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
2e900 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
2e910 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e920 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
2e930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e940 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2e950 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2e960 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2e970 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2e980 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
2e990 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2e9a0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
2e9b0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2e9c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2e9d0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2e9e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2e9f0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2ea00 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2ea10 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2ea20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
2ea30 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2ea40 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
2ea50 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
2ea60 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
2ea70 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
2ea80 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
2ea90 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
2eaa0 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
2eab0 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
2eac0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2ead0 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
2eae0 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
2eaf0 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
2eb00 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
2eb10 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
2eb20 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
2eb30 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
2eb40 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
2eb50 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
2eb60 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
2eb70 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
2eb80 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
2eb90 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
2eba0 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
2ebb0 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
2ebc0 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
2ebd0 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
2ebe0 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
2ebf0 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
2ec00 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
2ec10 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
2ec20 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2ec30 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2ec40 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
2ec50 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2ec60 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2ec70 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2ec80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2ec90 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2eca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ecb0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2ecc0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2ecd0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
2ece0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2ecf0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
2ed00 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2ed10 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2ed20 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
2ed30 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
2ed40 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
2ed50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2ed60 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
2ed70 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2ed80 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
2ed90 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
2eda0 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
2edb0 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
2edc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2edd0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
2ede0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2edf0 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
2ee00 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
2ee10 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
2ee20 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
2ee30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ee40 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2ee50 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
2ee60 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
2ee70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ee80 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
2ee90 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
2eea0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2eeb0 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
2eec0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2eed0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2eee0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
2eef0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
2ef00 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
2ef10 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2ef20 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
2ef30 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
2ef40 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
2ef50 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2ef60 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2ef70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2ef80 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
2ef90 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
2efa0 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
2efb0 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
2efc0 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
2efd0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
2efe0 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
2eff0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
2f000 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
2f010 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2f020 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
2f030 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
2f040 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
2f050 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
2f060 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
2f070 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2f080 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
2f090 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
2f0a0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
2f0b0 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
2f0c0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
2f0d0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
2f0e0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
2f0f0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
2f100 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
2f110 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2f120 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
2f130 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
2f140 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
2f150 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
2f160 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
2f170 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
2f180 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49  OMEM].)^.*/.SQLI
2f190 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2f1a0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2f1b0 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
2f1c0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2f1d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f1e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f1f0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
2f200 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2f210 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2f220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f230 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
2f240 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2f250 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65  QLITE_API double
2f260 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f270 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2f280 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2f290 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f2a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2f2b0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2f2c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2f2d0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
2f2e0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
2f2f0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
2f300 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f310 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2f320 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
2f330 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2f340 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
2f350 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f360 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2f370 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f380 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2f390 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f3a0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2f3b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2f3c0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
2f3d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f3e0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2f3f0 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  I sqlite3_value 
2f400 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2f410 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2f420 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f430 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f440 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
2f450 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2f460 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ject.**.** ^The 
2f470 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f480 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2f490 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
2f4a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2f4b0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
2f4c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
2f4d0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
2f4e0 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
2f4f0 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
2f500 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
2f510 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
2f520 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
2f530 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
2f540 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
2f550 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
2f560 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2f570 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
2f580 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
2f590 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
2f5a0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2f5b0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
2f5c0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2f5d0 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
2f5e0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2f5f0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
2f600 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f610 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
2f620 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
2f630 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
2f640 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
2f650 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2f660 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
2f670 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
2f680 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
2f690 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
2f6a0 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
2f6b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f6c0 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
2f6d0 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
2f6e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
2f6f0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
2f700 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
2f710 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
2f720 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
2f730 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
2f740 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
2f750 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
2f760 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
2f770 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
2f780 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2f790 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
2f7a0 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
2f7b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
2f7c0 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
2f7d0 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
2f7e0 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
2f7f0 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
2f800 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
2f810 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
2f820 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2f830 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2f840 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
2f850 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
2f860 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2f870 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2f880 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2f890 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
2f8a0 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
2f8b0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
2f8c0 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
2f8d0 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
2f8e0 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53  corruption..*/.S
2f8f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2f900 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
2f910 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2f920 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2f930 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
2f940 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2f950 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
2f960 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
2f970 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2f980 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
2f990 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f9a0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
2f9b0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2f9c0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
2f9d0 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
2f9e0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
2f9f0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
2fa00 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
2fa10 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
2fa20 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
2fa30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2fa40 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
2fa50 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
2fa60 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
2fa70 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
2fa80 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
2fa90 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
2faa0 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
2fab0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2fac0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
2fad0 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
2fae0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2faf0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
2fb00 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
2fb10 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
2fb20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2fb30 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2fb40 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2fb50 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
2fb60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2fb70 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2fb80 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
2fb90 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
2fba0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2fbb0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
2fbc0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
2fbd0 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
2fbe0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2fbf0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
2fc00 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
2fc10 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2fc20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2fc30 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2fc40 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2fc50 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
2fc60 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
2fc70 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
2fc80 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
2fc90 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
2fca0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
2fcb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
2fcc0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
2fcd0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
2fce0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
2fcf0 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
2fd00 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2fd10 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
2fd20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2fd30 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49  ment] S..*/.SQLI
2fd40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2fd50 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
2fd60 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2fd70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fd80 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
2fd90 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
2fda0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
2fdb0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
2fdc0 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
2fdd0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
2fde0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2fdf0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
2fe00 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
2fe10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2fe20 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
2fe30 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2fe40 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
2fe50 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
2fe60 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
2fe70 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
2fe80 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
2fe90 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2fea0 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
2feb0 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
2fec0 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
2fed0 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
2fee0 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
2fef0 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
2ff00 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
2ff10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2ff20 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
2ff30 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
2ff40 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  r.** the second 
2ff50 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
2ff60 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
2ff70 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
2ff80 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
2ff90 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
2ffa0 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
2ffb0 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
2ffc0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
2ffd0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
2ffe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2fff0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
30000 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
30010 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
30020 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
30030 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
30040 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
30050 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
30060 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
30070 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
30080 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
30090 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
300a0 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
300b0 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
300c0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
300d0 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
300e0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
300f0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
30100 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
30110 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
30120 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
30130 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
30140 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
30150 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
30160 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
30170 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
30180 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
30190 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
301a0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
301b0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
301c0 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
301d0 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
301e0 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
301f0 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
30200 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
30210 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
30220 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
30230 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
30240 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
30250 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
30260 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
30270 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
30280 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
30290 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
302a0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
302b0 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
302c0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
302d0 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
302e0 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
302f0 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
30300 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30310 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
30320 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
30330 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
30340 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
30350 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
30360 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
30370 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
30380 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
30390 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
303a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
303b0 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
303c0 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
303d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
303e0 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
303f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
30400 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
30410 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
30420 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
30430 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
30440 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
30450 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
30460 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
30470 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65  parameters.  Eve
30480 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ry SQL function 
30490 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
304a0 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77  ust be able to w
304b0 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d  ork.** with UTF-
304c0 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20  8, UTF-16le, or 
304d0 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73  UTF-16be.  But s
304e0 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ome implementati
304f0 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f  ons may be.** mo
30500 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74  re efficient wit
30510 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74  h one encoding t
30520 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41  han another.  ^A
30530 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
30540 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  y.** invoke sqli
30550 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30560 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
30570 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30580 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  16() multiple.**
30590 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
305a0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75  same function bu
305b0 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
305c0 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74   values of eText
305d0 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  Rep..** ^When mu
305e0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
305f0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
30600 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
30610 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
30620 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
30630 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
30640 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
30650 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
30660 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
30670 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
30680 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
30690 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
306a0 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74   not care what t
306b0 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20  ext.** encoding 
306c0 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
306d0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
306e0 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c  t should be [SQL
306f0 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ANY]..**.** 
30700 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61  ^(The fifth para
30710 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
30720 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
30730 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
30740 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
30750 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
30760 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
30770 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
30780 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
30790 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ].)^.**.** ^The 
307a0 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61  sixth, seventh a
307b0 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65  nd eighth parame
307c0 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
307d0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
307e0 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
307f0 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
30800 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
30810 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
30820 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
30830 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
30840 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
30850 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
30860 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
30870 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
30880 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
30890 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70  inters must be p
308a0 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
308b0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
308c0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
308d0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
308e0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
308f0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
30900 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
30910 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
30920 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20  LL pointer must 
30930 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
30940 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20  unc. ^To delete 
30950 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
30960 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
30970 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
30980 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72  ULL pointers for
30990 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
309a0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73  ion.** callbacks
309b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65  ..**.** ^(If the
309c0 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
309d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
309e0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
309f0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
30a00 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74   then it is dest
30a10 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61  ructor for the a
30a20 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
30a30 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65  pointer. .** The
30a40 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69   destructor is i
30a50 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
30a60 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
30a70 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62  ted, either by b
30a80 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64  eing.** overload
30a90 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64  ed or when the d
30aa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30ab0 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20  on closes.)^.** 
30ac0 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
30ad0 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20  is also invoked 
30ae0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  if the call to.*
30af0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
30b00 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66  _function_v2() f
30b10 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74  ails..** ^When t
30b20 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61  he destructor ca
30b30 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65  llback of the te
30b40 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  nth parameter is
30b50 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20   invoked, it.** 
30b60 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67  is passed a sing
30b70 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
30b80 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  h is a copy of t
30b90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
30ba0 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ata .** pointer 
30bb0 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69  which was the fi
30bc0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  fth parameter to
30bd0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30be0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  function_v2()..*
30bf0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d  *.** ^It is perm
30c00 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
30c10 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
30c20 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
30c30 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
30c40 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
30c50 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
30c60 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
30c70 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
30c80 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
30c90 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
30ca0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
30cb0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
30cc0 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
30cd0 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
30ce0 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
30cf0 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
30d00 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
30d10 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
30d20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70   ^A function imp
30d30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
30d40 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
30d50 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
30d60 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
30d70 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
30d80 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
30d90 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
30da0 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20  ative nArg.  ^A 
30db0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
30dc0 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78  he preferred tex
30dd0 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61  t encoding.** ma
30de0 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61  tches the databa
30df0 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61  se encoding is a
30e00 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68   better.** match
30e10 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
30e20 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
30e30 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
30e40 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69  .  .** ^A functi
30e50 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
30e60 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
30e70 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
30e80 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
30e90 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
30ea0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
30eb0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
30ec0 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
30ed0 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
30ee0 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
30ef0 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e  .**.** ^Built-in
30f00 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
30f10 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20  e overloaded by 
30f20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  new application-
30f30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
30f40 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70  s..**.** ^An app
30f50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30f60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72   function is per
30f70 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f  mitted to call o
30f80 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
30f90 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
30fa0 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20  ver, such calls 
30fb0 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73  must not.** clos
30fc0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
30fd0 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69  onnection nor fi
30fe0 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20  nalize or reset 
30ff0 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
31000 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69  statement in whi
31010 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ch the function 
31020 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
31030 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31040 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31050 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
31060 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
31070 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
31080 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
31090 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
310a0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
310b0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
310c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
310d0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
310e0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
310f0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
31100 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
31110 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
31120 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
31130 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
31140 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
31150 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31160 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
31170 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
31180 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
31190 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
311a0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
311b0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
311c0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
311d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
311e0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
311f0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
31200 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
31210 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
31220 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
31230 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
31240 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31250 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
31260 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
31270 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a  te_function_v2(.
31280 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
31290 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
312a0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
312b0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
312c0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
312d0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
312e0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
312f0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
31300 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
31310 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
31320 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
31330 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
31340 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
31350 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
31360 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  text*),.  void(*
31370 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
31380 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
31390 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
313a0 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
313b0 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
313c0 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
313d0 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
313e0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
313f0 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
31400 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
31410 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31420 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
31430 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
31440 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
31450 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
31460 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
31470 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
31480 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
31490 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
314a0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
314b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
314c0 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
314d0 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
314e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
314f0 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
31500 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
31510 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
31520 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
31530 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
31540 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31550 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
31560 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
31570 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
31580 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
31590 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
315a0 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
315b0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
315c0 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
315d0 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
315e0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
315f0 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
31600 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
31610 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
31620 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
31630 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
31640 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
31650 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
31660 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
31670 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
31680 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
31690 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
316a0 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74  to tell you what
316b0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
316c0 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
316d0 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
316e0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
316f0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
31700 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31710 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
31720 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  text*);.SQLITE_A
31730 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
31740 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
31750 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
31760 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
31770 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
31780 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
31790 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
317a0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
317b0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
317c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
317d0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
317e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
317f0 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
31800 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
31810 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
31820 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
31830 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
31840 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
31850 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
31860 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
31870 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
31880 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
31890 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
318a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23  qlite3_int64);.#
318b0 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
318c0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
318d0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
318e0 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a  rameter Values.*
318f0 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
31900 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
31910 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
31920 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
31930 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
31940 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
31950 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
31960 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
31970 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
31980 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
31990 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
319a0 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
319b0 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
319c0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
319d0 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
319e0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
319f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31a00 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
31a10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31a20 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
31a30 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
31a40 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
31a50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
31a60 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
31a70 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
31a80 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
31a90 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
31aa0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
31ab0 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
31ac0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31ad0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
31ae0 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
31af0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
31b00 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
31b10 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
31b20 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
31b30 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
31b40 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
31b50 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
31b60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31b70 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
31b80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
31b90 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
31ba0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
31bb0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
31bc0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
31bd0 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
31be0 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
31bf0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
31c00 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
31c10 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
31c20 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
31c30 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
31c40 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
31c50 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
31c60 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
31c70 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
31c80 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20  ** except that  
31c90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
31ca0 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
31cb0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
31cc0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
31cd0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
31ce0 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
31cf0 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
31d00 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
31d10 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
31d20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
31d30 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
31d40 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
31d50 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
31d60 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
31d70 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
31d80 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
31d90 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
31da0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
31db0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
31dc0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
31dd0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
31de0 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
31df0 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
31e00 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
31e10 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
31e20 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
31e30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
31e40 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
31e50 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
31e60 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
31e70 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
31e80 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
31e90 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
31ea0 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
31eb0 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
31ec0 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
31ed0 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
31ee0 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
31ef0 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
31f00 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
31f10 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
31f20 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
31f30 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
31f40 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
31f50 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
31f60 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
31f70 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
31f80 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
31f90 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
31fa0 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
31fb0 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
31fc0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
31fd0 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
31fe0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
31ff0 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
32000 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
32010 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
32020 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
32030 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
32040 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
32050 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
32060 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
32070 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
32080 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
32090 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
320a0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
320b0 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
320c0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
320d0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
320e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
320f0 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
32100 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32110 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
32120 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
32130 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
32140 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
32150 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
32160 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
32170 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
32180 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
32190 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
321a0 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
321b0 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ers..*/.SQLITE_A
321c0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
321d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
321e0 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
321f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
32200 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
32210 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
32220 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
32230 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
32240 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
32250 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
32260 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73  ITE_API double s
32270 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
32280 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
32290 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
322a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
322b0 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
322c0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
322d0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
322e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
322f0 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
32300 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
32310 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
32320 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
32330 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
32340 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
32350 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
32360 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32370 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
32380 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
32390 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
323a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
323b0 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
323c0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
323d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
323e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
323f0 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
32400 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
32410 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
32420 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
32430 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
32440 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
32450 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
32460 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32470 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32480 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
32490 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
324a0 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65  text.**.** Imple
324b0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67  mentations of ag
324c0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
324d0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a  tions use this.*
324e0 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  * routine to all
324f0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72  ocate memory for
32500 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
32510 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tate..**.** ^The
32520 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
32530 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
32540 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
32550 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
32560 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69   .** for a parti
32570 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20  cular aggregate 
32580 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
32590 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20  .** allocates N 
325a0 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
325b0 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72  s out that memor
325c0 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
325d0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
325e0 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e  he new memory. ^
325f0 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
32600 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
32610 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
32620 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
32630 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
32640 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
32650 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68   instance,.** th
32660 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
32670 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69   returned.  Sqli
32680 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
32690 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61  ntext() is norma
326a0 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e  lly.** called on
326b0 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f  ce for each invo
326c0 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53  cation of the xS
326d0 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64  tep callback and
326e0 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73   then one.** las
326f0 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  t time when the 
32700 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
32710 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57  is invoked.  ^(W
32720 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63  hen no rows matc
32730 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74  h.** an aggregat
32740 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74  e query, the xSt
32750 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ep() callback of
32760 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
32770 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  unction.** imple
32780 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76  mentation is nev
32790 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46  er called and xF
327a0 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64  inal() is called
327b0 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a   exactly once..*
327c0 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73  * In those cases
327d0 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  , sqlite3_aggreg
327e0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69  ate_context() mi
327f0 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f  ght be called fo
32800 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  r the.** first t
32810 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  ime from within 
32820 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a  xFinal().)^.**.*
32830 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61  * ^The sqlite3_a
32840 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32850 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65  (C,N) routine re
32860 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
32870 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20  nter if N is.** 
32880 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
32890 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66  al to zero or if
328a0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
328b0 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
328c0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
328d0 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
328e0 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
328f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
32900 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
32910 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
32920 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
32930 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
32940 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
32950 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
32960 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
32970 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
32980 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
32990 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
329a0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
329b0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
329c0 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
329d0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
329e0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a  * allocation.)^.
329f0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75  **.** ^SQLite au
32a00 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
32a10 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
32a20 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71  ocated by .** sq
32a30 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
32a40 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74  context() when t
32a50 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65  he aggregate que
32a60 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
32a70 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
32a80 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
32a90 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
32aa0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
32ab0 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
32ac0 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
32ad0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
32ae0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
32af0 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20  xStep or xFinal 
32b00 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
32b10 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
32b20 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
32b30 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
32b40 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
32b50 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
32b60 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
32b70 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
32b80 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
32b90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
32ba0 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
32bb0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
32bc0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
32bd0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
32be0 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
32bf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32c00 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
32c10 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
32c20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
32c30 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
32c40 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
32c50 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
32c60 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
32c70 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
32c80 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
32c90 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
32ca0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
32cb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
32cc0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
32cd0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32ce0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
32cf0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
32d00 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
32d10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
32d20 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
32d30 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
32d40 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
32d50 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
32d60 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
32d70 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
32d80 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32d90 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
32da0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
32db0 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
32dc0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
32dd0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
32de0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
32df0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
32e00 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
32e10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
32e20 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
32e30 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
32e40 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
32e50 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
32e60 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
32e70 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
32e80 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
32e90 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
32ea0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32eb0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
32ec0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32ed0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
32ee0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
32ef0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
32f00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32f10 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32f20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
32f30 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
32f40 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
32f50 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
32f60 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
32f70 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
32f80 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
32f90 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
32fa0 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
32fb0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
32fc0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
32fd0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
32fe0 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
32ff0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
33000 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
33010 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
33020 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
33030 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
33040 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
33050 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
33060 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
33070 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
33080 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
33090 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
330a0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
330b0 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
330c0 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
330d0 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
330e0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
330f0 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
33100 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
33110 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
33120 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
33130 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
33140 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
33150 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
33160 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
33170 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
33180 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
33190 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
331a0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
331b0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
331c0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
331d0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
331e0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
331f0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
33200 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
33210 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
33220 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
33230 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
33240 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
33250 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ocation..**.** ^
33260 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
33270 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
33280 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
33290 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
332a0 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
332b0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
332c0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
332d0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
332e0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
332f0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
33300 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33310 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
33320 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61  f no metadata ha
33330 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62  s been ever.** b
33340 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
33350 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  Nth argument of 
33360 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72  the function, or
33370 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   if the correspo
33380 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  nding.** functio
33390 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  n parameter has 
333a0 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68  changed since th
333b0 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20  e meta-data was 
333c0 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  set,.** then sql
333d0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
333e0 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
333f0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
33400 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
33410 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
33420 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20  rface saves the 
33430 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e  metadata.** poin
33440 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72  ted to by its 3r
33450 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
33460 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  he metadata for 
33470 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
33480 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
33490 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
334a0 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65  function.  Subse
334b0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
334c0 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
334d0 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65  xdata() might re
334e0 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20  turn this data, 
334f0 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74  if it has.** not
33500 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e   been destroyed.
33510 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f  .** ^If it is no
33520 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
33530 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
33540 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e  estructor.** fun
33550 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74  ction given by t
33560 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
33570 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
33580 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20  auxdata() on.** 
33590 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65  the metadata whe
335a0 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
335b0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
335c0 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
335d0 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
335e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
335f0 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
33600 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
33610 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
33620 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
33630 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
33640 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61  op metadata on a
33650 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ny.** parameter 
33660 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
33670 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54  at any time.  ^T
33680 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
33690 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
336a0 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
336b0 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
336c0 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
336d0 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
336e0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
336f0 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
33700 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
33710 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
33720 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
33730 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e  that are constan
33740 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t at compile tim
33750 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  e. This includes
33760 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
33770 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
33780 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs].)^.**.** The
33790 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
337a0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
337b0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
337c0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
337d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
337e0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
337f0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
33800 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
33810 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33820 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54  *, int N);.SQLIT
33830 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
33840 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
33850 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33860 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
33870 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
33880 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
33890 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
338a0 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
338b0 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
338c0 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
338d0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
338e0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
338f0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
33900 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
33910 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
33920 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
33930 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
33940 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68  blob()].  ^If th
33950 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
33960 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
33970 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
33980 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
33990 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
339a0 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
339b0 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
339c0 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
339d0 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
339e0 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53  oyed.  ^The.** S
339f0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
33a00 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
33a10 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
33a20 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
33a30 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
33a40 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
33a50 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
33a60 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
33a70 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
33a80 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
33a90 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
33aa0 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
33ab0 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
33ac0 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
33ad0 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
33ae0 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20  C++ compilers.  
33af0 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31  See ticket #2191
33b00 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
33b10 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
33b20 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
33b30 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
33b40 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
33b50 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
33b60 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
33b70 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
33b80 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
33b90 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
33ba0 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
33bb0 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
33bc0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
33bd0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a  SQL Function.**.
33be0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
33bf0 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
33c00 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
33c10 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
33c20 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
33c30 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
33c40 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
33c50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
33c60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
33c70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
33c80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
33c90 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
33ca0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
33cb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
33cc0 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
33cd0 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
33ce0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
33cf0 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
33d00 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
33d10 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
33d20 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
33d30 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
33d40 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
33d50 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
33d60 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
33d70 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
33d80 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
33d90 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
33da0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
33db0 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
33dc0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
33dd0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
33de0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33df0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
33e00 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
33e10 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
33e20 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
33e30 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
33e40 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
33e50 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
33e60 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
33e70 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
33e80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33e90 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
33ea0 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
33eb0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
33ec0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33ed0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33ee0 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
33ef0 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
33f00 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
33f10 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
33f20 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
33f30 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
33f40 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
33f50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33f60 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
33f70 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
33f80 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
33f90 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33fa0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
33fb0 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
33fc0 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
33fd0 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
33fe0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
33ff0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34000 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
34010 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
34020 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
34030 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
34040 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
34050 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
34060 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
34070 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
34080 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
34090 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
340a0 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
340b0 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
340c0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
340d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
340e0 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
340f0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
34100 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
34110 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
34120 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
34130 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
34140 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34150 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
34160 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
34170 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
34180 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
34190 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
341a0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
341b0 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
341c0 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
341d0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
341e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
341f0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
34200 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34210 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
34220 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
34230 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
34240 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
34250 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
34260 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
34270 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
34280 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
34290 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
342a0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
342b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
342c0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
342d0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
342e0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
342f0 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
34300 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
34310 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
34320 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
34330 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
34340 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34350 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
34360 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
34370 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
34380 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
34390 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
343a0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
343b0 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
343c0 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
343d0 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
343e0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
343f0 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
34400 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
34410 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
34420 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
34430 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34440 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
34450 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
34460 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
34470 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
34480 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
34490 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
344a0 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
344b0 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
344c0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
344d0 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
344e0 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
344f0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
34500 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
34510 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
34520 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
34530 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
34540 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
34550 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
34560 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34570 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
34580 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
34590 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
345a0 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
345b0 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
345c0 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e   BLOB is too lon
345d0 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a  g to represent..
345e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
345f0 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28  e3_result_nomem(
34600 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
34610 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
34620 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
34630 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
34640 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
34650 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
34660 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34670 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72  sult_int() inter
34680 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
34690 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
346a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
346b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
346c0 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  n to be the 32-b
346d0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
346e0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
346f0 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
34700 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ment..** ^The sq
34710 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
34720 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
34730 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
34740 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
34750 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34760 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
34770 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
34780 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
34790 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
347a0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
347b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
347c0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
347d0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
347e0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
347f0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
34800 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34810 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
34820 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
34830 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34840 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  xt(), sqlite3_re
34850 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a  sult_text16(),.*
34860 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
34870 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64  _text16le(), and
34880 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34890 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72  text16be() inter
348a0 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65  faces.** set the
348b0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
348c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
348d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
348e0 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78  n to be.** a tex
348f0 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  t string which i
34900 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
34910 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e   UTF-8, UTF-16 n
34920 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
34930 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
34940 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le endian, or UT
34950 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c  F-16 big endian,
34960 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
34970 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20  * ^SQLite takes 
34980 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
34990 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
349a0 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
349b0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
349c0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
349d0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
349e0 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  faces..** ^If th
349f0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
34a00 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
34a10 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
34a20 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
34a30 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
34a40 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
34a50 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
34a60 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
34a70 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
34a80 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
34a90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
34aa0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
34ab0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34ac0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34ad0 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
34ae0 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
34af0 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
34b00 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
34b10 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
34b20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
34b30 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
34b40 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
34b50 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
34b60 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
34b70 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
34b80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
34b90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34ba0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34bb0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
34bc0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
34bd0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
34be0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
34bf0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
34c00 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
34c10 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
34c20 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
34c30 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
34c40 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
34c50 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
34c60 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
34c70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
34c80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34c90 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
34ca0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
34cb0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
34cc0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
34cd0 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
34ce0 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
34cf0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
34d00 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
34d10 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
34d20 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
34d30 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
34d40 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
34d50 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
34d60 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
34d70 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
34d80 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
34d90 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
34da0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
34db0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
34dc0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
34dd0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
34de0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
34df0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
34e00 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
34e10 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
34e20 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
34e30 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
34e40 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
34e50 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
34e60 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
34e70 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
34e80 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
34e90 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
34ea0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34eb0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
34ec0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
34ed0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
34ee0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
34ef0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34f00 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
34f10 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
34f20 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34f30 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
34f40 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
34f50 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
34f60 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
34f70 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
34f80 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
34f90 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
34fa0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
34fb0 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
34fc0 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
34fd0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
34fe0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
34ff0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
35000 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
35010 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
35020 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
35030 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
35040 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
35050 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
35060 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
35070 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
35080 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35090 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
350a0 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
350b0 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
350c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
350d0 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
350e0 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
350f0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
35100 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
35110 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
35120 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
35130 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
35140 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
35150 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
35160 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35170 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
35180 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
35190 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
351a0 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
351b0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
351c0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
351d0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
351e0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
351f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35200 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
35210 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
35220 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
35230 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
35240 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
35250 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
35260 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
35270 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35280 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
35290 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
352a0 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  r*, int);.SQLITE
352b0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
352c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
352d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
352e0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
352f0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
35300 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
35310 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
35320 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
35330 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
35340 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35350 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
35360 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35370 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
35380 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35390 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
353a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
353b0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
353c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
353d0 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
353e0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
353f0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
35400 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
35410 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
35420 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
35430 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
35440 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
35450 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
35460 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
35470 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
35480 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35490 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
354a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
354b0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
354c0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
354d0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
354e0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
354f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35500 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
35510 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
35520 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35530 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35540 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
35550 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35560 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
35570 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
35580 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
35590 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
355a0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
355b0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
355c0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
355d0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
355e0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
355f0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
35600 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35610 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
35620 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35630 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35640 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
35650 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
35660 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
35670 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
35680 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
35690 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ces.**.** ^These
356a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20   functions add, 
356b0 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66  remove, or modif
356c0 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20  y a [collation] 
356d0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
356e0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
356f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
35700 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
35710 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
35720 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
35730 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
35740 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
35750 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
35760 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35770 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
35780 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
35790 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
357a0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
357b0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
357c0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
357d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
357e0 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
357f0 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70   names that comp
35800 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64  are equal accord
35810 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ing to [sqlite3_
35820 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a  strnicmp()] are.
35830 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ** considered to
35840 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   be the same nam
35850 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74  e..**.** ^(The t
35860 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65  hird argument (e
35870 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65  TextRep) must be
35880 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
35890 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  tants:.** <ul>.*
358a0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
358b0 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TF8],.** <li> [S
358c0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a  QLITE_UTF16LE],.
358d0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
358e0 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16BE],.** <li
358f0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  > [SQLITE_UTF16]
35900 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
35910 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
35920 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  ED]..** </ul>)^.
35930 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70  ** ^The eTextRep
35940 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
35950 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e  ines the encodin
35960 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73  g of strings pas
35970 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  sed.** to the co
35980 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35990 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c   callback, xCall
359a0 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  back..** ^The [S
359b0 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64  QLITE_UTF16] and
359c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
359d0 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66  LIGNED] values f
359e0 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66  or eTextRep.** f
359f0 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20  orce strings to 
35a00 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61  be UTF16 with na
35a10 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
35a20 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
35a30 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
35a40 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52  value for eTextR
35a50 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67  ep forces string
35a60 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e  s to begin.** on
35a70 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64   an even byte ad
35a80 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dress..**.** ^Th
35a90 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
35aa0 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61  t, pArg, is an a
35ab0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
35ac0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
35ad0 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
35ae0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
35af0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
35b00 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35b10 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
35b20 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
35b30 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
35b40 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
35b50 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
35b60 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
35b70 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
35b80 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
35b90 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
35ba0 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
35bb0 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
35bc0 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
35bd0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
35be0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
35bf0 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
35c00 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
35c10 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
35c20 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
35c30 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
35c40 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
35c50 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
35c60 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
35c70 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
35c80 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
35c90 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
35ca0 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
35cb0 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
35cc0 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
35cd0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
35ce0 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer usable..
35cf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61  **.** ^The colla
35d00 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
35d10 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
35d20 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66  d with a copy of
35d30 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70   the pArg .** ap
35d40 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
35d50 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20  ointer and with 
35d60 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74  two strings in t
35d70 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
35d80 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
35d90 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
35da0 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  t.  The collatin
35db0 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
35dc0 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74  return an.** int
35dd0 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67  eger that is neg
35de0 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20  ative, zero, or 
35df0 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74  positive.** if t
35e00 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
35e10 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
35e20 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
35e30 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
35e40 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  nd,.** respectiv
35e50 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e  ely.  A collatin
35e60 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
35e70 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
35e80 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a  e same answer.**
35e90 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20   given the same 
35ea0 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20  inputs.  If two 
35eb0 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e  or more collatin
35ec0 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
35ed0 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f  registered.** to
35ee0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74   the same collat
35ef0 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20  ion name (using 
35f00 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
35f10 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20  ep values) then 
35f20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65  all.** must give
35f30 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61   an equivalent a
35f40 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b  nswer when invok
35f50 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65  ed with equivale
35f60 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  nt strings..** T
35f70 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
35f80 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20  ction must obey 
35f90 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  the following pr
35fa0 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c  operties for all
35fb0 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42  .** strings A, B
35fc0 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c  , and C:.**.** <
35fd0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ol>.** <li> If A
35fe0 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a  ==B then B==A..*
35ff0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61  * <li> If A==B a
36000 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d  nd B==C then A==
36010 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  C..** <li> If A&
36020 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41  lt;B THEN B&gt;A
36030 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
36040 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74  t;B and B&lt;C t
36050 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c  hen A&lt;C..** <
36060 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  /ol>.**.** If a 
36070 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36080 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20  on fails any of 
36090 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72  the above constr
360a0 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a  aints and that.*
360b0 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  * collating func
360c0 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65  tion is  registe
360d0 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68  red and used, th
360e0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
360f0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20  of SQLite.** is 
36100 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
36110 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
36120 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
36130 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
36140 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36150 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74  llation().** wit
36160 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74  h the addition t
36170 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79  hat the xDestroy
36180 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
36190 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65  oked on pArg whe
361a0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  n.** the collati
361b0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
361c0 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c  eleted..** ^Coll
361d0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
361e0 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e  are deleted when
361f0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
36200 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a  dden by later.**
36210 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
36220 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
36230 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
36240 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  en the.** [datab
36250 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36260 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
36270 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
36280 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44  ]..**.** ^The xD
36290 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
362a0 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61  is <u>not</u> ca
362b0 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20  lled if the .** 
362c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
362d0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75  ollation_v2() fu
362e0 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41  nction fails.  A
362f0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
36300 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
36310 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36320 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20  ion_v2() with a 
36330 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f  non-NULL xDestro
36340 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  y argument shoul
36350 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20  d .** check the 
36360 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20  return code and 
36370 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61  dispose of the a
36380 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
36390 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73  pointer.** thems
363a0 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61  elves rather tha
363b0 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69  n expecting SQLi
363c0 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  te to deal with 
363d0 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20  it for them..** 
363e0 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e  This is differen
363f0 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68  t from every oth
36400 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
36410 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73  ace.  The incons
36420 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75  istency .** is u
36430 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63  nfortunate but c
36440 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
36450 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
36460 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20  g backwards .** 
36470 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
36480 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
36490 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
364a0 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
364b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
364c0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
364d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
364e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
364f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
36500 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
36510 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
36520 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
36530 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
36540 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
36550 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
36560 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
36570 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  void*).);.SQLITE
36580 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36590 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
365a0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
365b0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
365c0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
365d0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
365e0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
365f0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
36600 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
36610 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
36620 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
36630 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c  y)(void*).);.SQL
36640 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
36650 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36660 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
36670 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
36680 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
36690 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
366a0 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
366b0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
366c0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
366d0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
366e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
366f0 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
36700 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
36710 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
36720 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
36730 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
36740 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
36750 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
36760 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
36770 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
36780 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
36790 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
367a0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
367b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
367c0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
367d0 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
367e0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
367f0 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
36800 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
36810 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
36820 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
36830 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
36840 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
36850 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
36860 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
36870 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
36880 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
36890 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
368a0 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
368b0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
368c0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
368d0 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
368e0 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
368f0 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
36900 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
36910 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
36920 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
36930 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
36940 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
36950 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
36960 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
36970 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
36980 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
36990 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
369a0 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
369b0 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
369c0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
369d0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
369e0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
369f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
36a00 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
36a10 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
36a20 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
36a30 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
36a40 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
36a50 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
36a60 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
36a70 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
36a80 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
36a90 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
36aa0 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
36ab0 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
36ac0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
36ad0 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
36ae0 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
36af0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
36b00 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
36b10 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
36b20 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
36b30 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
36b40 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
36b50 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
36b60 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
36b70 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
36b80 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
36b90 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
36ba0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
36bb0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
36bc0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
36bd0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36be0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  on_v2()]..*/.SQL
36bf0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
36c00 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
36c10 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
36c20 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
36c30 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
36c40 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
36c50 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
36c60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
36c70 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
36c80 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
36c90 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
36ca0 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
36cb0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
36cc0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
36cd0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65  void*).);..#ifde
36ce0 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44  f SQLITE_HAS_COD
36cf0 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  EC./*.** Specify
36d00 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
36d10 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
36d20 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
36d30 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
36d40 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
36d50 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
36d60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
36d70 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
36d80 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
36d90 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
36da0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
36db0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
36dc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
36dd0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
36de0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
36df0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
36e00 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
36e10 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
36e20 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
36e30 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
36e40 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
36e50 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
36e60 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
36e70 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
36e80 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
36e90 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
36ea0 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
36eb0 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
36ec0 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
36ed0 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
36ee0 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
36ef0 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
36f00 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
36f10 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
36f20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
36f30 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
36f40 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
36f50 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
36f60 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
36f70 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
36f80 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
36f90 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
36fa0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
36fb0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
36fc0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
36fd0 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
36fe0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70   */.);../*.** Sp
36ff0 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
37000 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53  tion key for a S
37010 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  EE database.  Un
37020 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
37030 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
37040 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  SEE routines wil
37050 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  l work..*/.SQLIT
37060 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
37070 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
37080 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
37090 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
370a0 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
370b0 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
370c0 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
370d0 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
370e0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
370f0 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
37100 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
37110 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
37120 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
37130 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
37140 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
37150 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rk..*/.SQLITE_AP
37160 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  I void sqlite3_a
37170 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
37180 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
37190 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
371a0 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
371b0 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
371c0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
371d0 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
371e0 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
371f0 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Time.**.** The 
37200 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
37210 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
37220 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
37230 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
37240 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
37250 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
37260 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
37270 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
37280 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
37290 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
372a0 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
372b0 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
372c0 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
372d0 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
372e0 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
372f0 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
37300 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
37310 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
37320 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
37330 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
37340 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
37350 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
37360 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
37370 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
37380 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
37390 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  * ^SQLite implem
373a0 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
373b0 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
373c0 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
373d0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
373e0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
373f0 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74  s] object.  If t
37400 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
37410 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66  od.** of the def
37420 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20  ault VFS is not 
37430 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72  implemented corr
37440 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d  ectly, or not im
37450 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20  plemented at.** 
37460 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65  all, then the be
37470 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
37480 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65  3_sleep() may de
37490 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64  viate from the d
374a0 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e  escription.** in
374b0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
374c0 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c  ragraphs..*/.SQL
374d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
374e0 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
374f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37500 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
37510 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
37520 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
37530 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
37540 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
37550 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
37560 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
37570 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
37580 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
37590 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
375a0 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
375b0 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
375c0 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
375d0 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
375e0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
375f0 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
37600 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
37610 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
37620 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
37630 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
37640 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
37650 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
37660 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
37670 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
37680 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
37690 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
376a0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
376b0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
376c0 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
376d0 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
376e0 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
376f0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
37700 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
37710 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
37720 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
37730 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
37740 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
37750 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
37760 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
37770 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
37780 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
37790 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
377a0 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
377b0 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
377c0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
377d0 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
377e0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
377f0 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
37800 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
37810 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
37820 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
37830 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
37840 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
37850 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37860 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
37870 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
37880 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
37890 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
378a0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
378b0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
378c0 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
378d0 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
378e0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
378f0 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
37900 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
37910 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
37920 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
37930 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
37940 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
37950 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
37960 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
37970 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
37980 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
37990 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
379a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
379b0 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
379c0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
379d0 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
379e0 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
379f0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
37a00 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
37a10 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
37a20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
37a30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
37a40 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
37a50 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
37a60 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37a70 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
37a80 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51  e avoided..*/.SQ
37a90 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
37aa0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
37ab0 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
37ac0 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72  PI3REF: Test For
37ad0 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
37ae0 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  e.** KEYWORDS: {
37af0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d  autocommit mode}
37b00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37b10 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
37b20 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  it() interface r
37b30 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
37b40 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68  or.** zero if th
37b50 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65  e given database
37b60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
37b70 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f  r is not in auto
37b80 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20  commit mode,.** 
37b90 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e  respectively.  ^
37ba0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
37bb0 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  is on by default
37bc0 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
37bd0 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
37be0 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73  d by a [BEGIN] s
37bf0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75  tatement..** ^Au
37c00 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
37c10 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
37c20 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
37c30 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
37c40 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
37c50 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
37c60 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
37c70 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
37c80 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
37c90 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69  action (errors i
37ca0 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
37cb0 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
37cc0 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  IOERR],.** [SQLI
37cd0 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
37ce0 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
37cf0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
37d00 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
37d10 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
37d20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
37d30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
37d40 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
37d50 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68  * find out wheth
37d60 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  er SQLite automa
37d70 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
37d80 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
37d90 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
37da0 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
37db0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
37dc0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
37dd0 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
37de0 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
37df0 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
37e00 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
37e10 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
37e20 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
37e30 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
37e40 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e  n value.** is un
37e50 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49  defined..*/.SQLI
37e60 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
37e70 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
37e80 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
37e90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
37ea0 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20  nd The Database 
37eb0 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70  Handle Of A Prep
37ec0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
37ed0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37ee0 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65  3_db_handle inte
37ef0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
37f00 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37f10 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
37f20 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72  * to which a [pr
37f30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
37f40 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65  ] belongs.  ^The
37f50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37f60 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e  ction].** return
37f70 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62  ed by sqlite3_db
37f80 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73  _handle is the s
37f90 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
37fa0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61  nnection].** tha
37fb0 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20  t was the first 
37fc0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
37fd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
37fe0 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28  are_v2()] call (
37ff0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  or its variants)
38000 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
38010 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20  o.** create the 
38020 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
38030 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f   first place..*/
38040 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
38050 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
38060 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
38070 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
38080 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65  PI3REF: Find the
38090 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
380a0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
380b0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  This interface r
380c0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
380d0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72   to the next [pr
380e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
380f0 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74  ] after.** pStmt
38100 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
38110 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
38120 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20  onnection] pDb. 
38130 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55   ^If pStmt is NU
38140 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  LL.** then this 
38150 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
38160 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
38170 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65  he first prepare
38180 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61  d statement.** a
38190 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
381a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
381b0 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66  ection pDb.  ^If
381c0 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61   no prepared sta
381d0 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66  tement.** satisf
381e0 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f  ies the conditio
381f0 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ns of this routi
38200 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e  ne, it returns N
38210 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
38220 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38230 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69  ion] pointer D i
38240 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  n a call to.** [
38250 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
38260 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66  t(D,S)] must ref
38270 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61  er to an open da
38280 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
38290 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74  tion and in part
382a0 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20  icular must not 
382b0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
382c0 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
382d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73   sqlite3_stmt *s
382e0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
382f0 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
38300 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
38310 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
38320 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
38330 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
38340 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
38350 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
38360 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
38370 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
38380 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
38390 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
383a0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
383b0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
383c0 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63  n is [COMMIT | c
383d0 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41  ommitted]..** ^A
383e0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
383f0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
38400 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
38410 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
38420 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
38430 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
38440 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
38450 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
38460 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
38470 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
38480 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
38490 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
384a0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
384b0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
384c0 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f  s [ROLLBACK | ro
384d0 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e  lled back]..** ^
384e0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
384f0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
38500 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
38510 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a  ollback_hook().*
38520 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
38530 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38540 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
38550 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61  ..** ^The pArg a
38560 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
38570 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
38580 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49   callback..** ^I
38590 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
385a0 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
385b0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
385c0 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
385d0 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
385e0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
385f0 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
38600 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
38610 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50  ommit_hook(D,C,P
38620 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f  ) and sqlite3_ro
38630 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c  llback_hook(D,C,
38640 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  P) functions.** 
38650 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67  return the P arg
38660 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
38670 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20  revious call of 
38680 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
38690 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  n.** on the same
386a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
386b0 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
386c0 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
386d0 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68  st call for each
386e0 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a   function on D..
386f0 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
38700 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
38710 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
38720 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
38730 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
38740 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38750 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
38760 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
38770 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
38780 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
38790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
387a0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
387b0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
387c0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
387d0 66 20 74 68 65 20