System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact bcfb7defdd83e1a575ea60959c74da3ddfa80c0a:


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 39 2e 20 20 42  ersion 3.7.9.  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 66 6f 6c 6c 6f 77 69 6e  .** The followin
28e0: 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65  g macros are use
28f0: 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74 65  d to cast pointe
2900: 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20 61  rs to integers a
2910: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 74  nd.** integers t
2920: 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68 65  o pointers.  The
2930: 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69 73   way you do this
2940: 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65   varies from one
2950: 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20   compiler.** to 
2960: 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65 20  the next, so we 
2970: 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20 74  have developed t
2980: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 74  he following set
2990: 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65 6e   of #if statemen
29a0: 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61 74  ts.** to generat
29b0: 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d 61  e appropriate ma
29c0: 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65 20  cros for a wide 
29d0: 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c 65  range of compile
29e0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  rs..**.** The co
29f0: 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 61 79  rrect "ANSI" way
2a00: 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20 74   to do this is t
2a10: 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 74 72  o use the intptr
2a20: 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e 66  _t type. .** Unf
2a30: 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61 74  ortunately, that
2a40: 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74 20   typedef is not 
2a50: 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c 6c  available on all
2a60: 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a 2a   compilers, or.*
2a70: 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 69 6c  * if it is avail
2a80: 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72 65  able, it require
2a90: 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f 66  s an #include of
2aa0: 20 73 70 65 63 69 66 69 63 20 68 65 61 64 65 72   specific header
2ab0: 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20 66  s.** that vary f
2ac0: 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65 20  rom one machine 
2ad0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a  to the next..**.
2ae0: 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30 3a  ** Ticket #3860:
2af0: 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d 34    The llvm-gcc-4
2b00: 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f 6d  .2 compiler from
2b10: 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f 6e   Apple chokes on
2b20: 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a 29  .** the ((void*)
2b30: 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 20  &((char*)0)[X]) 
2b40: 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74 20  construct.  But 
2b50: 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20 28  MSVC chokes on (
2b60: 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a 20  (void*)(X))..** 
2b70: 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64 65  So we have to de
2b80: 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73 20  fine the macros 
2b90: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61 79  in different way
2ba0: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  s depending on t
2bb0: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e 0a  he.** compiler..
2bc0: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f  */.#if defined(_
2bd0: 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29  _PTRDIFF_TYPE__)
2be0: 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20 73    /* This case s
2bf0: 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20 47  hould work for G
2c00: 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53  CC */.# define S
2c10: 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52  QLITE_INT_TO_PTR
2c20: 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f 5f  (X)  ((void*)(__
2c30: 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28  PTRDIFF_TYPE__)(
2c40: 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  X)).# define SQL
2c50: 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58  ITE_PTR_TO_INT(X
2c60: 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52 44  )  ((int)(__PTRD
2c70: 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29 0a  IFF_TYPE__)(X)).
2c80: 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 5f  #elif !defined(_
2c90: 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20 2f  _GNUC__)       /
2ca0: 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d 70  * Works for comp
2cb0: 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61 6e  ilers other than
2cc0: 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69 6e   LLVM */.# defin
2cd0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f  e SQLITE_INT_TO_
2ce0: 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29  PTR(X)  ((void*)
2cf0: 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 0a  &((char*)0)[X]).
2d00: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2d10: 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28  PTR_TO_INT(X)  (
2d20: 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58 29  (int)(((char*)X)
2d30: 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c 69  -(char*)0)).#eli
2d40: 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f 53  f defined(HAVE_S
2d50: 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55 73  TDINT_H)   /* Us
2d60: 65 20 74 68 69 73 20 63 61 73 65 20 69 66 20 77  e this case if w
2d70: 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 61 64  e have ANSI head
2d80: 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20  ers */.# define 
2d90: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54  SQLITE_INT_TO_PT
2da0: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 69  R(X)  ((void*)(i
2db0: 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20 64  ntptr_t)(X)).# d
2dc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52  efine SQLITE_PTR
2dd0: 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e  _TO_INT(X)  ((in
2de0: 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29  t)(intptr_t)(X))
2df0: 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 20 20  .#else          
2e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e10: 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20 77  /* Generates a w
2e20: 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74 20  arning - but it 
2e30: 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f 0a  always works */.
2e40: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2e50: 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20 28  INT_TO_PTR(X)  (
2e60: 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64 65  (void*)(X)).# de
2e70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f  fine SQLITE_PTR_
2e80: 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74  TO_INT(X)  ((int
2e90: 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a  )(X)).#endif../*
2ea0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 54  .** The SQLITE_T
2eb0: 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f 20  HREADSAFE macro 
2ec0: 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 64 20  must be defined 
2ed0: 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a 2a  as 0, 1, or 2..*
2ee0: 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78 65  * 0 means mutexe
2ef0: 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74 6c  s are permanentl
2f00: 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74 68  y disable and th
2f10: 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65 76  e library is nev
2f20: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 65  er.** threadsafe
2f30: 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20 6c  .  1 means the l
2f40: 69 62 72 61 72 79 20 69 73 20 73 65 72 69 61 6c  ibrary is serial
2f50: 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 74 68  ized which is th
2f60: 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65 76  e highest.** lev
2f70: 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66 65  el of threadsafe
2f80: 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68 65  ty.  2 means the
2f90: 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c 74 69   libary is multi
2fa0: 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74 69  threaded - multi
2fb0: 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20 63  ple.** threads c
2fc0: 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61 73  an use SQLite as
2fd0: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
2fe0: 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20 75  threads try to u
2ff0: 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  se the same.** d
3000: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3010: 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  on at the same t
3020: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65 72  ime..**.** Older
3030: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
3040: 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74 69  ite used an opti
3050: 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45 20  onal THREADSAFE 
3060: 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75 70  macro..** We sup
3070: 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c 65  port that for le
3080: 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64 65  gacy..*/.#if !de
3090: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48 52  fined(SQLITE_THR
30a0: 45 41 44 53 41 46 45 29 0a 23 69 66 20 64 65 66  EADSAFE).#if def
30b0: 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45 29  ined(THREADSAFE)
30c0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
30d0: 5f 54 48 52 45 41 44 53 41 46 45 20 54 48 52 45  _THREADSAFE THRE
30e0: 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23 20 64  ADSAFE.#else.# d
30f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 48 52  efine SQLITE_THR
3100: 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49 4d 50  EADSAFE 1 /* IMP
3110: 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30 39 20  : R-07272-22309 
3120: 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66  */.#endif.#endif
3130: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ../*.** The SQLI
3140: 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
3150: 41 54 55 53 20 6d 61 63 72 6f 20 6d 75 73 74 20  ATUS macro must 
3160: 62 65 20 64 65 66 69 6e 65 64 20 61 73 20 65 69  be defined as ei
3170: 74 68 65 72 20 30 20 6f 72 20 31 2e 0a 2a 2a 20  ther 0 or 1..** 
3180: 49 74 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  It determines wh
3190: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
31a0: 20 66 65 61 74 75 72 65 73 20 72 65 6c 61 74 65   features relate
31b0: 64 20 74 6f 20 0a 2a 2a 20 53 51 4c 49 54 45 5f  d to .** SQLITE_
31c0: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
31d0: 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 62   are available b
31e0: 79 20 64 65 66 61 75 6c 74 20 6f 72 20 6e 6f 74  y default or not
31f0: 2e 20 54 68 69 73 20 76 61 6c 75 65 20 63 61 6e  . This value can
3200: 0a 2a 2a 20 62 65 20 6f 76 65 72 72 69 64 64 65  .** be overridde
3210: 6e 20 61 74 20 72 75 6e 74 69 6d 65 20 75 73 69  n at runtime usi
3220: 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
3230: 6f 6e 66 69 67 28 29 20 41 50 49 2e 0a 2a 2f 0a  onfig() API..*/.
3240: 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c  #if !defined(SQL
3250: 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
3260: 54 41 54 55 53 29 0a 23 20 64 65 66 69 6e 65 20  TATUS).# define 
3270: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
3280: 45 4d 53 54 41 54 55 53 20 31 0a 23 65 6e 64 69  EMSTATUS 1.#endi
3290: 66 0a 0a 2f 2a 0a 2a 2a 20 45 78 61 63 74 6c 79  f../*.** Exactly
32a0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
32b0: 6f 77 69 6e 67 20 6d 61 63 72 6f 73 20 6d 75 73  owing macros mus
32c0: 74 20 62 65 20 64 65 66 69 6e 65 64 20 69 6e 20  t be defined in 
32d0: 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 73 70 65 63  order to.** spec
32e0: 69 66 79 20 77 68 69 63 68 20 6d 65 6d 6f 72 79  ify which memory
32f0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
3300: 79 73 74 65 6d 20 74 6f 20 75 73 65 2e 0a 2a 2a  ystem to use..**
3310: 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 53  .**     SQLITE_S
3320: 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 20 20 20  YSTEM_MALLOC    
3330: 20 20 20 20 20 20 2f 2f 20 55 73 65 20 6e 6f 72        // Use nor
3340: 6d 61 6c 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  mal system mallo
3350: 63 28 29 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  c().**     SQLIT
3360: 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 20 20  E_WIN32_MALLOC  
3370: 20 20 20 20 20 20 20 20 20 2f 2f 20 55 73 65 20           // Use 
3380: 57 69 6e 33 32 20 6e 61 74 69 76 65 20 68 65 61  Win32 native hea
3390: 70 20 41 50 49 0a 2a 2a 20 20 20 20 20 53 51 4c  p API.**     SQL
33a0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 20 20 20 20  ITE_MEMDEBUG    
33b0: 20 20 20 20 20 20 20 20 20 20 20 2f 2f 20 44 65             // De
33c0: 62 75 67 67 69 6e 67 20 76 65 72 73 69 6f 6e 20  bugging version 
33d0: 6f 66 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  of system malloc
33e0: 28 29 0a 2a 2a 0a 2a 2a 20 4f 6e 20 57 69 6e 64  ().**.** On Wind
33f0: 6f 77 73 2c 20 69 66 20 74 68 65 20 53 51 4c 49  ows, if the SQLI
3400: 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5f  TE_WIN32_MALLOC_
3410: 56 41 4c 49 44 41 54 45 20 6d 61 63 72 6f 20 69  VALIDATE macro i
3420: 73 20 64 65 66 69 6e 65 64 20 61 6e 64 20 74 68  s defined and th
3430: 65 0a 2a 2a 20 61 73 73 65 72 74 28 29 20 6d 61  e.** assert() ma
3440: 63 72 6f 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  cro is enabled, 
3450: 65 61 63 68 20 63 61 6c 6c 20 69 6e 74 6f 20 74  each call into t
3460: 68 65 20 57 69 6e 33 32 20 6e 61 74 69 76 65 20  he Win32 native 
3470: 68 65 61 70 20 73 75 62 73 79 73 74 65 6d 0a 2a  heap subsystem.*
3480: 2a 20 77 69 6c 6c 20 63 61 75 73 65 20 48 65 61  * will cause Hea
3490: 70 56 61 6c 69 64 61 74 65 20 74 6f 20 62 65 20  pValidate to be 
34a0: 63 61 6c 6c 65 64 2e 20 20 49 66 20 68 65 61 70  called.  If heap
34b0: 20 76 61 6c 69 64 61 74 69 6f 6e 20 73 68 6f 75   validation shou
34c0: 6c 64 20 66 61 69 6c 2c 20 61 6e 0a 2a 2a 20 61  ld fail, an.** a
34d0: 73 73 65 72 74 69 6f 6e 20 77 69 6c 6c 20 62 65  ssertion will be
34e0: 20 74 72 69 67 67 65 72 65 64 2e 0a 2a 2a 0a 2a   triggered..**.*
34f0: 2a 20 28 48 69 73 74 6f 72 69 63 61 6c 20 6e 6f  * (Historical no
3500: 74 65 3a 20 20 54 68 65 72 65 20 75 73 65 64 20  te:  There used 
3510: 74 6f 20 62 65 20 73 65 76 65 72 61 6c 20 6f 74  to be several ot
3520: 68 65 72 20 6f 70 74 69 6f 6e 73 2c 20 62 75 74  her options, but
3530: 20 77 65 27 76 65 0a 2a 2a 20 70 61 72 65 64 20   we've.** pared 
3540: 69 74 20 64 6f 77 6e 20 74 6f 20 6a 75 73 74 20  it down to just 
3550: 74 68 65 73 65 20 74 68 72 65 65 2e 29 0a 2a 2a  these three.).**
3560: 0a 2a 2a 20 49 66 20 6e 6f 6e 65 20 6f 66 20 74  .** If none of t
3570: 68 65 20 61 62 6f 76 65 20 61 72 65 20 64 65 66  he above are def
3580: 69 6e 65 64 2c 20 74 68 65 6e 20 73 65 74 20 53  ined, then set S
3590: 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c  QLITE_SYSTEM_MAL
35a0: 4c 4f 43 20 61 73 0a 2a 2a 20 74 68 65 20 64 65  LOC as.** the de
35b0: 66 61 75 6c 74 2e 0a 2a 2f 0a 23 69 66 20 64 65  fault..*/.#if de
35c0: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53  fined(SQLITE_SYS
35d0: 54 45 4d 5f 4d 41 4c 4c 4f 43 29 2b 64 65 66 69  TEM_MALLOC)+defi
35e0: 6e 65 64 28 53 51 4c 49 54 45 5f 57 49 4e 33 32  ned(SQLITE_WIN32
35f0: 5f 4d 41 4c 4c 4f 43 29 2b 64 65 66 69 6e 65 64  _MALLOC)+defined
3600: 28 53 51 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47  (SQLITE_MEMDEBUG
3610: 29 3e 31 0a 23 20 65 72 72 6f 72 20 22 41 74 20  )>1.# error "At 
3620: 6d 6f 73 74 20 6f 6e 65 20 6f 66 20 74 68 65 20  most one of the 
3630: 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6d 70 69 6c  following compil
3640: 65 2d 74 69 6d 65 20 63 6f 6e 66 69 67 75 72 61  e-time configura
3650: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 5c 0a 20 69  tion options\. i
3660: 73 20 61 6c 6c 6f 77 73 3a 20 53 51 4c 49 54 45  s allows: SQLITE
3670: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 2c 20  _SYSTEM_MALLOC, 
3680: 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
3690: 4c 4f 43 2c 20 53 51 4c 49 54 45 5f 4d 45 4d 44  LOC, SQLITE_MEMD
36a0: 45 42 55 47 22 0a 23 65 6e 64 69 66 0a 23 69 66  EBUG".#endif.#if
36b0: 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f   defined(SQLITE_
36c0: 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 29 2b 64  SYSTEM_MALLOC)+d
36d0: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 57 49  efined(SQLITE_WI
36e0: 4e 33 32 5f 4d 41 4c 4c 4f 43 29 2b 64 65 66 69  N32_MALLOC)+defi
36f0: 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45 4d 44 45  ned(SQLITE_MEMDE
3700: 42 55 47 29 3d 3d 30 0a 23 20 64 65 66 69 6e 65  BUG)==0.# define
3710: 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d   SQLITE_SYSTEM_M
3720: 41 4c 4c 4f 43 20 31 0a 23 65 6e 64 69 66 0a 0a  ALLOC 1.#endif..
3730: 2f 2a 0a 2a 2a 20 49 66 20 53 51 4c 49 54 45 5f  /*.** If SQLITE_
3740: 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49  MALLOC_SOFT_LIMI
3750: 54 20 69 73 20 6e 6f 74 20 7a 65 72 6f 2c 20 74  T is not zero, t
3760: 68 65 6e 20 74 72 79 20 74 6f 20 6b 65 65 70 20  hen try to keep 
3770: 74 68 65 0a 2a 2a 20 73 69 7a 65 73 20 6f 66 20  the.** sizes of 
3780: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
3790: 6e 73 20 62 65 6c 6f 77 20 74 68 69 73 20 76 61  ns below this va
37a0: 6c 75 65 20 77 68 65 72 65 20 70 6f 73 73 69 62  lue where possib
37b0: 6c 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69  le..*/.#if !defi
37c0: 6e 65 64 28 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f  ned(SQLITE_MALLO
37d0: 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 29 0a 23 20  C_SOFT_LIMIT).# 
37e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41  define SQLITE_MA
37f0: 4c 4c 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 20  LLOC_SOFT_LIMIT 
3800: 31 30 32 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  1024.#endif../*.
3810: 2a 2a 20 57 65 20 6e 65 65 64 20 74 6f 20 64 65  ** We need to de
3820: 66 69 6e 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52  fine _XOPEN_SOUR
3830: 43 45 20 61 73 20 66 6f 6c 6c 6f 77 73 20 69 6e  CE as follows in
3840: 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
3850: 0a 2a 2a 20 72 65 63 75 72 73 69 76 65 20 6d 75  .** recursive mu
3860: 74 65 78 65 73 20 6f 6e 20 6d 6f 73 74 20 55 6e  texes on most Un
3870: 69 78 20 73 79 73 74 65 6d 73 2e 20 20 42 75 74  ix systems.  But
3880: 20 4d 61 63 20 4f 53 20 58 20 69 73 20 64 69 66   Mac OS X is dif
3890: 66 65 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 5f  ferent..** The _
38a0: 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 64 65 66  XOPEN_SOURCE def
38b0: 69 6e 65 20 63 61 75 73 65 73 20 70 72 6f 62 6c  ine causes probl
38c0: 65 6d 73 20 66 6f 72 20 4d 61 63 20 4f 53 20 58  ems for Mac OS X
38d0: 20 77 65 20 61 72 65 20 74 6f 6c 64 2c 0a 2a 2a   we are told,.**
38e0: 20 73 6f 20 69 74 20 69 73 20 6f 6d 69 74 74 65   so it is omitte
38f0: 64 20 74 68 65 72 65 2e 20 20 53 65 65 20 74 69  d there.  See ti
3900: 63 6b 65 74 20 23 32 36 37 33 2e 0a 2a 2a 0a 2a  cket #2673..**.*
3910: 2a 20 4c 61 74 65 72 20 77 65 20 6c 65 61 72 6e  * Later we learn
3920: 20 74 68 61 74 20 5f 58 4f 50 45 4e 5f 53 4f 55   that _XOPEN_SOU
3930: 52 43 45 20 69 73 20 70 6f 6f 72 6c 79 20 6f 72  RCE is poorly or
3940: 20 69 6e 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20   incorrectly.** 
3950: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 6f 6e 20 73  implemented on s
3960: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 20 20 53 6f  ome systems.  So
3970: 20 77 65 20 61 76 6f 69 64 20 64 65 66 69 6e 69   we avoid defini
3980: 6e 67 20 69 74 20 61 74 20 61 6c 6c 0a 2a 2a 20  ng it at all.** 
3990: 69 66 20 69 74 20 69 73 20 61 6c 72 65 61 64 79  if it is already
39a0: 20 64 65 66 69 6e 65 64 20 6f 72 20 69 66 20 69   defined or if i
39b0: 74 20 69 73 20 75 6e 6e 65 65 64 65 64 20 62 65  t is unneeded be
39c0: 63 61 75 73 65 20 77 65 20 61 72 65 0a 2a 2a 20  cause we are.** 
39d0: 6e 6f 74 20 64 6f 69 6e 67 20 61 20 74 68 72 65  not doing a thre
39e0: 61 64 73 61 66 65 20 62 75 69 6c 64 2e 20 20 54  adsafe build.  T
39f0: 69 63 6b 65 74 20 23 32 36 38 31 2e 0a 2a 2a 0a  icket #2681..**.
3a00: 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 69 63 6b  ** See also tick
3a10: 65 74 20 23 32 37 34 31 2e 0a 2a 2f 0a 23 69 66  et #2741..*/.#if
3a20: 20 21 64 65 66 69 6e 65 64 28 5f 58 4f 50 45 4e   !defined(_XOPEN
3a30: 5f 53 4f 55 52 43 45 29 20 26 26 20 21 64 65 66  _SOURCE) && !def
3a40: 69 6e 65 64 28 5f 5f 44 41 52 57 49 4e 5f 5f 29  ined(__DARWIN__)
3a50: 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 5f 41   && !defined(__A
3a60: 50 50 4c 45 5f 5f 29 20 26 26 20 53 51 4c 49 54  PPLE__) && SQLIT
3a70: 45 5f 54 48 52 45 41 44 53 41 46 45 0a 23 20 20  E_THREADSAFE.#  
3a80: 64 65 66 69 6e 65 20 5f 58 4f 50 45 4e 5f 53 4f  define _XOPEN_SO
3a90: 55 52 43 45 20 35 30 30 20 20 2f 2a 20 4e 65 65  URCE 500  /* Nee
3aa0: 64 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 70 74  ded to enable pt
3ab0: 68 72 65 61 64 20 72 65 63 75 72 73 69 76 65 20  hread recursive 
3ac0: 6d 75 74 65 78 65 73 20 2a 2f 0a 23 65 6e 64 69  mutexes */.#endi
3ad0: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 54 43 4c  f../*.** The TCL
3ae0: 20 68 65 61 64 65 72 73 20 61 72 65 20 6f 6e 6c   headers are onl
3af0: 79 20 6e 65 65 64 65 64 20 77 68 65 6e 20 63 6f  y needed when co
3b00: 6d 70 69 6c 69 6e 67 20 74 68 65 20 54 43 4c 20  mpiling the TCL 
3b10: 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 23 69 66  bindings..*/.#if
3b20: 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f   defined(SQLITE_
3b30: 54 43 4c 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  TCL) || defined(
3b40: 54 43 4c 53 48 29 0a 23 20 69 6e 63 6c 75 64 65  TCLSH).# include
3b50: 20 3c 74 63 6c 2e 68 3e 0a 23 65 6e 64 69 66 0a   <tcl.h>.#endif.
3b60: 0a 2f 2a 0a 2a 2a 20 4d 61 6e 79 20 70 65 6f 70  ./*.** Many peop
3b70: 6c 65 20 61 72 65 20 66 61 69 6c 69 6e 67 20 74  le are failing t
3b80: 6f 20 73 65 74 20 2d 44 4e 44 45 42 55 47 3d 31  o set -DNDEBUG=1
3b90: 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67 20   when compiling 
3ba0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 53 65 74 74 69  SQLite..** Setti
3bb0: 6e 67 20 4e 44 45 42 55 47 20 6d 61 6b 65 73 20  ng NDEBUG makes 
3bc0: 74 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c 65 72  the code smaller
3bd0: 20 61 6e 64 20 72 75 6e 20 66 61 73 74 65 72 2e   and run faster.
3be0: 20 20 53 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69    So the followi
3bf0: 6e 67 0a 2a 2a 20 6c 69 6e 65 73 20 61 72 65 20  ng.** lines are 
3c00: 61 64 64 65 64 20 74 6f 20 61 75 74 6f 6d 61 74  added to automat
3c10: 69 63 61 6c 6c 79 20 73 65 74 20 4e 44 45 42 55  ically set NDEBU
3c20: 47 20 75 6e 6c 65 73 73 20 74 68 65 20 2d 44 53  G unless the -DS
3c30: 51 4c 49 54 45 5f 44 45 42 55 47 3d 31 0a 2a 2a  QLITE_DEBUG=1.**
3c40: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2e 20   option is set. 
3c50: 20 54 68 75 73 20 4e 44 45 42 55 47 20 62 65 63   Thus NDEBUG bec
3c60: 6f 6d 65 73 20 61 6e 20 6f 70 74 2d 69 6e 20 72  omes an opt-in r
3c70: 61 74 68 65 72 20 74 68 61 6e 20 61 6e 20 6f 70  ather than an op
3c80: 74 2d 6f 75 74 0a 2a 2a 20 66 65 61 74 75 72 65  t-out.** feature
3c90: 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 65  ..*/.#if !define
3ca0: 64 28 4e 44 45 42 55 47 29 20 26 26 20 21 64 65  d(NDEBUG) && !de
3cb0: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 42  fined(SQLITE_DEB
3cc0: 55 47 29 20 0a 23 20 64 65 66 69 6e 65 20 4e 44  UG) .# define ND
3cd0: 45 42 55 47 20 31 0a 23 65 6e 64 69 66 0a 0a 2f  EBUG 1.#endif../
3ce0: 2a 0a 2a 2a 20 54 68 65 20 74 65 73 74 63 61 73  *.** The testcas
3cf0: 65 28 29 20 6d 61 63 72 6f 20 69 73 20 75 73 65  e() macro is use
3d00: 64 20 74 6f 20 61 69 64 20 69 6e 20 63 6f 76 65  d to aid in cove
3d10: 72 61 67 65 20 74 65 73 74 69 6e 67 2e 20 20 57  rage testing.  W
3d20: 68 65 6e 20 0a 2a 2a 20 64 6f 69 6e 67 20 63 6f  hen .** doing co
3d30: 76 65 72 61 67 65 20 74 65 73 74 69 6e 67 2c 20  verage testing, 
3d40: 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 20 69 6e  the condition in
3d50: 73 69 64 65 20 74 68 65 20 61 72 67 75 6d 65 6e  side the argumen
3d60: 74 20 74 6f 0a 2a 2a 20 74 65 73 74 63 61 73 65  t to.** testcase
3d70: 28 29 20 6d 75 73 74 20 62 65 20 65 76 61 6c 75  () must be evalu
3d80: 61 74 65 64 20 62 6f 74 68 20 74 72 75 65 20 61  ated both true a
3d90: 6e 64 20 66 61 6c 73 65 20 69 6e 20 6f 72 64 65  nd false in orde
3da0: 72 20 74 6f 0a 2a 2a 20 67 65 74 20 66 75 6c 6c  r to.** get full
3db0: 20 62 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65   branch coverage
3dc0: 2e 20 20 54 68 65 20 74 65 73 74 63 61 73 65 28  .  The testcase(
3dd0: 29 20 6d 61 63 72 6f 20 69 73 20 69 6e 73 65 72  ) macro is inser
3de0: 74 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 65  ted.** to help e
3df0: 6e 73 75 72 65 20 61 64 65 71 75 61 74 65 20 74  nsure adequate t
3e00: 65 73 74 20 63 6f 76 65 72 61 67 65 20 69 6e 20  est coverage in 
3e10: 70 6c 61 63 65 73 20 77 68 65 72 65 20 73 69 6d  places where sim
3e20: 70 6c 65 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  ple.** condition
3e30: 2f 64 65 63 69 73 69 6f 6e 20 63 6f 76 65 72 61  /decision covera
3e40: 67 65 20 69 73 20 69 6e 61 64 65 71 75 61 74 65  ge is inadequate
3e50: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
3e60: 74 65 73 74 63 61 73 65 28 29 0a 2a 2a 20 63 61  testcase().** ca
3e70: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6d 61 6b  n be used to mak
3e80: 65 20 73 75 72 65 20 62 6f 75 6e 64 61 72 79 20  e sure boundary 
3e90: 76 61 6c 75 65 73 20 61 72 65 20 74 65 73 74 65  values are teste
3ea0: 64 2e 20 20 46 6f 72 0a 2a 2a 20 62 69 74 6d 61  d.  For.** bitma
3eb0: 73 6b 20 74 65 73 74 73 2c 20 74 65 73 74 63 61  sk tests, testca
3ec0: 73 65 28 29 20 63 61 6e 20 62 65 20 75 73 65 64  se() can be used
3ed0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 65 61   to make sure ea
3ee0: 63 68 20 62 69 74 0a 2a 2a 20 69 73 20 73 69 67  ch bit.** is sig
3ef0: 6e 69 66 69 63 61 6e 74 20 61 6e 64 20 75 73 65  nificant and use
3f00: 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 2e  d at least once.
3f10: 20 20 4f 6e 20 73 77 69 74 63 68 20 73 74 61 74    On switch stat
3f20: 65 6d 65 6e 74 73 0a 2a 2a 20 77 68 65 72 65 20  ements.** where 
3f30: 6d 75 6c 74 69 70 6c 65 20 63 61 73 65 73 20 67  multiple cases g
3f40: 6f 20 74 6f 20 74 68 65 20 73 61 6d 65 20 62 6c  o to the same bl
3f50: 6f 63 6b 20 6f 66 20 63 6f 64 65 2c 20 74 65 73  ock of code, tes
3f60: 74 63 61 73 65 28 29 0a 2a 2a 20 63 61 6e 20 69  tcase().** can i
3f70: 6e 73 75 72 65 20 74 68 61 74 20 61 6c 6c 20 63  nsure that all c
3f80: 61 73 65 73 20 61 72 65 20 65 76 61 6c 75 61 74  ases are evaluat
3f90: 65 64 2e 0a 2a 2a 0a 2a 2f 0a 23 69 66 64 65 66  ed..**.*/.#ifdef
3fa0: 20 53 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 45   SQLITE_COVERAGE
3fb0: 5f 54 45 53 54 0a 53 51 4c 49 54 45 5f 50 52 49  _TEST.SQLITE_PRI
3fc0: 56 41 54 45 20 20 20 76 6f 69 64 20 73 71 6c 69  VATE   void sqli
3fd0: 74 65 33 43 6f 76 65 72 61 67 65 28 69 6e 74 29  te3Coverage(int)
3fe0: 3b 0a 23 20 64 65 66 69 6e 65 20 74 65 73 74 63  ;.# define testc
3ff0: 61 73 65 28 58 29 20 20 69 66 28 20 58 20 29 7b  ase(X)  if( X ){
4000: 20 73 71 6c 69 74 65 33 43 6f 76 65 72 61 67 65   sqlite3Coverage
4010: 28 5f 5f 4c 49 4e 45 5f 5f 29 3b 20 7d 0a 23 65  (__LINE__); }.#e
4020: 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 74 65 73  lse.# define tes
4030: 74 63 61 73 65 28 58 29 0a 23 65 6e 64 69 66 0a  tcase(X).#endif.
4040: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 54 45 53 54 4f  ./*.** The TESTO
4050: 4e 4c 59 20 6d 61 63 72 6f 20 69 73 20 75 73 65  NLY macro is use
4060: 64 20 74 6f 20 65 6e 63 6c 6f 73 65 20 76 61 72  d to enclose var
4070: 69 61 62 6c 65 20 64 65 63 6c 61 72 61 74 69 6f  iable declaratio
4080: 6e 73 20 6f 72 0a 2a 2a 20 6f 74 68 65 72 20 62  ns or.** other b
4090: 69 74 73 20 6f 66 20 63 6f 64 65 20 74 68 61 74  its of code that
40a0: 20 61 72 65 20 6e 65 65 64 65 64 20 74 6f 20 73   are needed to s
40b0: 75 70 70 6f 72 74 20 74 68 65 20 61 72 67 75 6d  upport the argum
40c0: 65 6e 74 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ents.** within t
40d0: 65 73 74 63 61 73 65 28 29 20 61 6e 64 20 61 73  estcase() and as
40e0: 73 65 72 74 28 29 20 6d 61 63 72 6f 73 2e 0a 2a  sert() macros..*
40f0: 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 4e  /.#if !defined(N
4100: 44 45 42 55 47 29 20 7c 7c 20 64 65 66 69 6e 65  DEBUG) || define
4110: 64 28 53 51 4c 49 54 45 5f 43 4f 56 45 52 41 47  d(SQLITE_COVERAG
4120: 45 5f 54 45 53 54 29 0a 23 20 64 65 66 69 6e 65  E_TEST).# define
4130: 20 54 45 53 54 4f 4e 4c 59 28 58 29 20 20 58 0a   TESTONLY(X)  X.
4140: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 54  #else.# define T
4150: 45 53 54 4f 4e 4c 59 28 58 29 0a 23 65 6e 64 69  ESTONLY(X).#endi
4160: 66 0a 0a 2f 2a 0a 2a 2a 20 53 6f 6d 65 74 69 6d  f../*.** Sometim
4170: 65 73 20 77 65 20 6e 65 65 64 20 61 20 73 6d 61  es we need a sma
4180: 6c 6c 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 64  ll amount of cod
4190: 65 20 73 75 63 68 20 61 73 20 61 20 76 61 72 69  e such as a vari
41a0: 61 62 6c 65 20 69 6e 69 74 69 61 6c 69 7a 61 74  able initializat
41b0: 69 6f 6e 0a 2a 2a 20 74 6f 20 73 65 74 75 70 20  ion.** to setup 
41c0: 66 6f 72 20 61 20 6c 61 74 65 72 20 61 73 73 65  for a later asse
41d0: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 2e 20  rt() statement. 
41e0: 20 57 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20   We do not want 
41f0: 74 68 69 73 20 63 6f 64 65 20 74 6f 0a 2a 2a 20  this code to.** 
4200: 61 70 70 65 61 72 20 77 68 65 6e 20 61 73 73 65  appear when asse
4210: 72 74 28 29 20 69 73 20 64 69 73 61 62 6c 65 64  rt() is disabled
4220: 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
4230: 20 6d 61 63 72 6f 20 69 73 20 74 68 65 72 65 66   macro is theref
4240: 6f 72 65 0a 2a 2a 20 75 73 65 64 20 74 6f 20 63  ore.** used to c
4250: 6f 6e 74 61 69 6e 20 74 68 61 74 20 73 65 74 75  ontain that setu
4260: 70 20 63 6f 64 65 2e 20 20 54 68 65 20 22 56 56  p code.  The "VV
4270: 41 22 20 61 63 72 6f 6e 79 6d 20 73 74 61 6e 64  A" acronym stand
4280: 73 20 66 6f 72 0a 2a 2a 20 22 56 65 72 69 66 69  s for.** "Verifi
4290: 63 61 74 69 6f 6e 2c 20 56 61 6c 69 64 61 74 69  cation, Validati
42a0: 6f 6e 2c 20 61 6e 64 20 41 63 63 72 65 64 69 74  on, and Accredit
42b0: 61 74 69 6f 6e 22 2e 20 20 49 6e 20 6f 74 68 65  ation".  In othe
42c0: 72 20 77 6f 72 64 73 2c 20 74 68 65 0a 2a 2a 20  r words, the.** 
42d0: 63 6f 64 65 20 77 69 74 68 69 6e 20 56 56 41 5f  code within VVA_
42e0: 4f 4e 4c 59 28 29 20 77 69 6c 6c 20 6f 6e 6c 79  ONLY() will only
42f0: 20 72 75 6e 20 64 75 72 69 6e 67 20 76 65 72 69   run during veri
4300: 66 69 63 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  fication process
4310: 65 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e  es..*/.#ifndef N
4320: 44 45 42 55 47 0a 23 20 64 65 66 69 6e 65 20 56  DEBUG.# define V
4330: 56 41 5f 4f 4e 4c 59 28 58 29 20 20 58 0a 23 65  VA_ONLY(X)  X.#e
4340: 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 56 56 41  lse.# define VVA
4350: 5f 4f 4e 4c 59 28 58 29 0a 23 65 6e 64 69 66 0a  _ONLY(X).#endif.
4360: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 41 4c 57 41 59  ./*.** The ALWAY
4370: 53 20 61 6e 64 20 4e 45 56 45 52 20 6d 61 63 72  S and NEVER macr
4380: 6f 73 20 73 75 72 72 6f 75 6e 64 20 62 6f 6f 6c  os surround bool
4390: 65 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 73 20  ean expressions 
43a0: 77 68 69 63 68 20 0a 2a 2a 20 61 72 65 20 69 6e  which .** are in
43b0: 74 65 6e 64 65 64 20 74 6f 20 61 6c 77 61 79 73  tended to always
43c0: 20 62 65 20 74 72 75 65 20 6f 72 20 66 61 6c 73   be true or fals
43d0: 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  e, respectively.
43e0: 20 20 53 75 63 68 0a 2a 2a 20 65 78 70 72 65 73    Such.** expres
43f0: 73 69 6f 6e 73 20 63 6f 75 6c 64 20 62 65 20 6f  sions could be o
4400: 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
4410: 63 6f 64 65 20 63 6f 6d 70 6c 65 74 65 6c 79 2e  code completely.
4420: 20 20 42 75 74 20 74 68 65 79 0a 2a 2a 20 61 72    But they.** ar
4430: 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 61 20  e included in a 
4440: 66 65 77 20 63 61 73 65 73 20 69 6e 20 6f 72 64  few cases in ord
4450: 65 72 20 74 6f 20 65 6e 68 61 6e 63 65 20 74 68  er to enhance th
4460: 65 20 72 65 73 69 6c 69 65 6e 63 65 0a 2a 2a 20  e resilience.** 
4470: 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 75 6e 65  of SQLite to une
4480: 78 70 65 63 74 65 64 20 62 65 68 61 76 69 6f 72  xpected behavior
4490: 20 2d 20 74 6f 20 6d 61 6b 65 20 74 68 65 20 63   - to make the c
44a0: 6f 64 65 20 22 73 65 6c 66 2d 68 65 61 6c 69 6e  ode "self-healin
44b0: 67 22 0a 2a 2a 20 6f 72 20 22 64 75 63 74 69 6c  g".** or "ductil
44c0: 65 22 20 72 61 74 68 65 72 20 74 68 61 6e 20 62  e" rather than b
44d0: 65 69 6e 67 20 22 62 72 69 74 74 6c 65 22 20 61  eing "brittle" a
44e0: 6e 64 20 63 72 61 73 68 69 6e 67 20 61 74 20 74  nd crashing at t
44f0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 68 69 6e 74  he first.** hint
4500: 20 6f 66 20 75 6e 70 6c 61 6e 6e 65 64 20 62 65   of unplanned be
4510: 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e  havior..**.** In
4520: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 41 4c   other words, AL
4530: 57 41 59 53 20 61 6e 64 20 4e 45 56 45 52 20 61  WAYS and NEVER a
4540: 72 65 20 61 64 64 65 64 20 66 6f 72 20 64 65 66  re added for def
4550: 65 6e 73 69 76 65 20 63 6f 64 65 2e 0a 2a 2a 0a  ensive code..**.
4560: 2a 2a 20 57 68 65 6e 20 64 6f 69 6e 67 20 63 6f  ** When doing co
4570: 76 65 72 61 67 65 20 74 65 73 74 69 6e 67 20 41  verage testing A
4580: 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45 52 20  LWAYS and NEVER 
4590: 61 72 65 20 68 61 72 64 2d 63 6f 64 65 64 20 74  are hard-coded t
45a0: 6f 0a 2a 2a 20 62 65 20 74 72 75 65 20 61 6e 64  o.** be true and
45b0: 20 66 61 6c 73 65 20 73 6f 20 74 68 61 74 20 74   false so that t
45c0: 68 65 20 75 6e 72 65 61 63 68 61 62 6c 65 20 63  he unreachable c
45d0: 6f 64 65 20 74 68 65 6e 20 73 70 65 63 69 66 79  ode then specify
45e0: 20 77 69 6c 6c 0a 2a 2a 20 6e 6f 74 20 62 65 20   will.** not be 
45f0: 63 6f 75 6e 74 65 64 20 61 73 20 75 6e 74 65 73  counted as untes
4600: 74 65 64 20 63 6f 64 65 2e 0a 2a 2f 0a 23 69 66  ted code..*/.#if
4610: 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f   defined(SQLITE_
4620: 43 4f 56 45 52 41 47 45 5f 54 45 53 54 29 0a 23  COVERAGE_TEST).#
4630: 20 64 65 66 69 6e 65 20 41 4c 57 41 59 53 28 58   define ALWAYS(X
4640: 29 20 20 20 20 20 20 28 31 29 0a 23 20 64 65 66  )      (1).# def
4650: 69 6e 65 20 4e 45 56 45 52 28 58 29 20 20 20 20  ine NEVER(X)    
4660: 20 20 20 28 30 29 0a 23 65 6c 69 66 20 21 64 65     (0).#elif !de
4670: 66 69 6e 65 64 28 4e 44 45 42 55 47 29 0a 23 20  fined(NDEBUG).# 
4680: 64 65 66 69 6e 65 20 41 4c 57 41 59 53 28 58 29  define ALWAYS(X)
4690: 20 20 20 20 20 20 28 28 58 29 3f 31 3a 28 61 73        ((X)?1:(as
46a0: 73 65 72 74 28 30 29 2c 30 29 29 0a 23 20 64 65  sert(0),0)).# de
46b0: 66 69 6e 65 20 4e 45 56 45 52 28 58 29 20 20 20  fine NEVER(X)   
46c0: 20 20 20 20 28 28 58 29 3f 28 61 73 73 65 72 74      ((X)?(assert
46d0: 28 30 29 2c 31 29 3a 30 29 0a 23 65 6c 73 65 0a  (0),1):0).#else.
46e0: 23 20 64 65 66 69 6e 65 20 41 4c 57 41 59 53 28  # define ALWAYS(
46f0: 58 29 20 20 20 20 20 20 28 58 29 0a 23 20 64 65  X)      (X).# de
4700: 66 69 6e 65 20 4e 45 56 45 52 28 58 29 20 20 20  fine NEVER(X)   
4710: 20 20 20 20 28 58 29 0a 23 65 6e 64 69 66 0a 0a      (X).#endif..
4720: 2f 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 72 75  /*.** Return tru
4730: 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
4740: 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 20 69  the input is a i
4750: 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 74  nteger that is t
4760: 6f 6f 20 6c 61 72 67 65 0a 2a 2a 20 74 6f 20 66  oo large.** to f
4770: 69 74 20 69 6e 20 33 32 2d 62 69 74 73 2e 20 20  it in 32-bits.  
4780: 54 68 69 73 20 6d 61 63 72 6f 20 69 73 20 75 73  This macro is us
4790: 65 64 20 69 6e 73 69 64 65 20 6f 66 20 76 61 72  ed inside of var
47a0: 69 6f 75 73 20 74 65 73 74 63 61 73 65 28 29 0a  ious testcase().
47b0: 2a 2a 20 6d 61 63 72 6f 73 20 74 6f 20 76 65 72  ** macros to ver
47c0: 69 66 79 20 74 68 61 74 20 77 65 20 68 61 76 65  ify that we have
47d0: 20 74 65 73 74 65 64 20 53 51 4c 69 74 65 20 66   tested SQLite f
47e0: 6f 72 20 6c 61 72 67 65 2d 66 69 6c 65 20 73 75  or large-file su
47f0: 70 70 6f 72 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  pport..*/.#defin
4800: 65 20 49 53 5f 42 49 47 5f 49 4e 54 28 58 29 20  e IS_BIG_INT(X) 
4810: 20 28 28 28 58 29 26 7e 28 69 36 34 29 30 78 66   (((X)&~(i64)0xf
4820: 66 66 66 66 66 66 66 29 21 3d 30 29 0a 0a 2f 2a  fffffff)!=0)../*
4830: 0a 2a 2a 20 54 68 65 20 6d 61 63 72 6f 20 75 6e  .** The macro un
4840: 6c 69 6b 65 6c 79 28 29 20 69 73 20 61 20 68 69  likely() is a hi
4850: 6e 74 20 74 68 61 74 20 73 75 72 72 6f 75 6e 64  nt that surround
4860: 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 65  s a boolean.** e
4870: 78 70 72 65 73 73 69 6f 6e 20 74 68 61 74 20 69  xpression that i
4880: 73 20 75 73 75 61 6c 6c 79 20 66 61 6c 73 65 2e  s usually false.
4890: 20 20 4d 61 63 72 6f 20 6c 69 6b 65 6c 79 28 29    Macro likely()
48a0: 20 73 75 72 72 6f 75 6e 64 73 0a 2a 2a 20 61 20   surrounds.** a 
48b0: 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73 73 69  boolean expressi
48c0: 6f 6e 20 74 68 61 74 20 69 73 20 75 73 75 61 6c  on that is usual
48d0: 6c 79 20 74 72 75 65 2e 20 20 47 43 43 20 69 73  ly true.  GCC is
48e0: 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 75 73 65 20   able to.** use 
48f0: 74 68 65 73 65 20 68 69 6e 74 73 20 74 6f 20 67  these hints to g
4900: 65 6e 65 72 61 74 65 20 62 65 74 74 65 72 20 63  enerate better c
4910: 6f 64 65 2c 20 73 6f 6d 65 74 69 6d 65 73 2e 0a  ode, sometimes..
4920: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f  */.#if defined(_
4930: 5f 47 4e 55 43 5f 5f 29 20 26 26 20 30 0a 23 20  _GNUC__) && 0.# 
4940: 64 65 66 69 6e 65 20 6c 69 6b 65 6c 79 28 58 29  define likely(X)
4950: 20 20 20 20 5f 5f 62 75 69 6c 74 69 6e 5f 65 78      __builtin_ex
4960: 70 65 63 74 28 28 58 29 2c 31 29 0a 23 20 64 65  pect((X),1).# de
4970: 66 69 6e 65 20 75 6e 6c 69 6b 65 6c 79 28 58 29  fine unlikely(X)
4980: 20 20 5f 5f 62 75 69 6c 74 69 6e 5f 65 78 70 65    __builtin_expe
4990: 63 74 28 28 58 29 2c 30 29 0a 23 65 6c 73 65 0a  ct((X),0).#else.
49a0: 23 20 64 65 66 69 6e 65 20 6c 69 6b 65 6c 79 28  # define likely(
49b0: 58 29 20 20 20 20 21 21 28 58 29 0a 23 20 64 65  X)    !!(X).# de
49c0: 66 69 6e 65 20 75 6e 6c 69 6b 65 6c 79 28 58 29  fine unlikely(X)
49d0: 20 20 21 21 28 58 29 0a 23 65 6e 64 69 66 0a 0a    !!(X).#endif..
49e0: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
49f0: 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65 33 2e  Include sqlite3.
4a00: 68 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  h in the middle 
4a10: 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a  of sqliteInt.h *
4a20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  **************/.
4a30: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
4a40: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
4a50: 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e3.h ***********
4a60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4a70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  **************/.
4a80: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
4a90: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
4aa0: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
4ab0: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
4ac0: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
4ad0: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
4ae0: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
4af0: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
4b00: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
4b10: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
4b20: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
4b30: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
4b40: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
4b50: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
4b60: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
4b70: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
4b80: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
4b90: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
4ba0: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
4bb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4bc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4bd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4be0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4bf0: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
4c00: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
4c10: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
4c20: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
4c30: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
4c40: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
4c50: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
4c60: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
4c70: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
4c80: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
4c90: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
4ca0: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
4cb0: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
4cc0: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
4cd0: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
4ce0: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
4cf0: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
4d00: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
4d10: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
4d20: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
4d30: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
4d40: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
4d50: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
4d60: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
4d70: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
4d80: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
4d90: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
4da0: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
4db0: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
4dc0: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
4dd0: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
4de0: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
4df0: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
4e00: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
4e10: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
4e20: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
4e30: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
4e40: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
4e50: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
4e60: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
4e70: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
4e80: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
4e90: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
4ea0: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
4eb0: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
4ec0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
4ed0: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
4ee0: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
4ef0: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
4f00: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
4f10: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
4f20: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
4f30: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
4f40: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
4f50: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
4f60: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
4f70: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
4f80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
4f90: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
4fa0: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
4fb0: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
4fc0: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
4fd0: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
4fe0: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
4ff0: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
5000: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
5010: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
5020: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
5030: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
5040: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
5050: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
5060: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
5070: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
5080: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
5090: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
50a0: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
50b0: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
50c0: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
50d0: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
50e0: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
50f0: 2a 2f 0a 23 69 66 20 30 0a 65 78 74 65 72 6e 20  */.#if 0.extern 
5100: 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f  "C" {.#endif.../
5110: 2a 0a 2a 2a 20 41 64 64 20 74 68 65 20 61 62 69  *.** Add the abi
5120: 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65  lity to override
5130: 20 27 65 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66   'extern'.*/.#if
5140: 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54 45  ndef SQLITE_EXTE
5150: 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  RN.# define SQLI
5160: 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72 6e  TE_EXTERN extern
5170: 0a 23 65 6e 64 69 66 0a 0a 23 69 66 6e 64 65 66  .#endif..#ifndef
5180: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
5190: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
51a0: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54  #endif.../*.** T
51b0: 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f  hese no-op macro
51c0: 73 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72  s are used in fr
51d0: 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  ont of interface
51e0: 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a  s to mark those.
51f0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73  ** interfaces as
5200: 20 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74   either deprecat
5210: 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74  ed or experiment
5220: 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61  al.  New applica
5230: 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
5240: 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74  not use deprecat
5250: 65 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20  ed interfaces - 
5260: 74 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74  they are support
5270: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
5280: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
5290: 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69  only.  Applicati
52a0: 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c  on writers shoul
52b0: 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a  d be aware that.
52c0: 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ** experimental 
52d0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73  interfaces are s
52e0: 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
52f0: 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73   in point releas
5300: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es..**.** These 
5310: 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72  macros used to r
5320: 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75  esolve to variou
5330: 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69  s kinds of compi
5340: 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a  ler magic that.*
5350: 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65  * would generate
5360: 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65   warning message
5370: 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65  s when they were
5380: 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74   used.  But that
5390: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67  .** compiler mag
53a0: 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65  ic ended up gene
53b0: 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c  rating such a fl
53c0: 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f  urry of bug repo
53d0: 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68  rts.** that we h
53e0: 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c  ave taken it all
53f0: 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61   out and gone ba
5400: 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70  ck to using simp
5410: 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f  le.** noop macro
5420: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
5430: 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a  LITE_DEPRECATED.
5440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
5450: 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a  XPERIMENTAL../*.
5460: 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20  ** Ensure these 
5470: 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74  symbols were not
5480: 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65   defined by some
5490: 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72   previous header
54a0: 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66   file..*/.#ifdef
54b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
54c0: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56  # undef SQLITE_V
54d0: 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69  ERSION.#endif.#i
54e0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
54f0: 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64  ION_NUMBER.# und
5500: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ef SQLITE_VERSIO
5510: 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a  N_NUMBER.#endif.
5520: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5530: 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69   Compile-Time Li
5540: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
5550: 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  mbers.**.** ^(Th
5560: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  e [SQLITE_VERSIO
5570: 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  N] C preprocesso
5580: 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73  r macro in the s
5590: 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a  qlite3.h header.
55a0: 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20  ** evaluates to 
55b0: 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
55c0: 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c   that is the SQL
55d0: 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74  ite version in t
55e0: 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e  he.** format "X.
55f0: 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20  Y.Z" where X is 
5600: 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f  the major versio
5610: 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73  n number (always
5620: 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65   3 for.** SQLite
5630: 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20  3) and Y is the 
5640: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75  minor version nu
5650: 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68  mber and Z is th
5660: 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72  e release number
5670: 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .)^.** ^(The [SQ
5680: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
5690: 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73  BER] C preproces
56a0: 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76  sor macro resolv
56b0: 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  es to an integer
56c0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c  .** with the val
56d0: 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20  ue (X*1000000 + 
56e0: 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72  Y*1000 + Z) wher
56f0: 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72  e X, Y, and Z ar
5700: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75  e the same.** nu
5710: 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53  mbers used in [S
5720: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29  QLITE_VERSION].)
5730: 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ^.** The SQLITE_
5740: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66  VERSION_NUMBER f
5750: 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c  or any given rel
5760: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77  ease of SQLite w
5770: 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c  ill also.** be l
5780: 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72  arger than the r
5790: 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63  elease from whic
57a0: 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e  h it is derived.
57b0: 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a    Either Y will.
57c0: 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74  ** be held const
57d0: 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62  ant and Z will b
57e0: 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72  e incremented or
57f0: 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20   else Y will be 
5800: 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61  incremented.** a
5810: 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73  nd Z will be res
5820: 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  et to zero..**.*
5830: 2a 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20  * Since version 
5840: 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73  3.6.18, SQLite s
5850: 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62  ource code has b
5860: 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68  een stored in th
5870: 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74  e.** <a href="ht
5880: 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d  tp://www.fossil-
5890: 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c  scm.org/">Fossil
58a0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
58b0: 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73  anagement.** sys
58c0: 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53  tem</a>.  ^The S
58d0: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20  QLITE_SOURCE_ID 
58e0: 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20  macro evaluates 
58f0: 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77  to.** a string w
5900: 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20  hich identifies 
5910: 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65  a particular che
5920: 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a  ck-in of SQLite.
5930: 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f  ** within its co
5940: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
5950: 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20  gement system.  
5960: 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  ^The SQLITE_SOUR
5970: 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20  CE_ID.** string 
5980: 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
5990: 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68  e and time of th
59a0: 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29  e check-in (UTC)
59b0: 20 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20   and an SHA1.** 
59c0: 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69  hash of the enti
59d0: 72 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a  re source tree..
59e0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
59f0: 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  [sqlite3_libvers
5a00: 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ion()],.** [sqli
5a10: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
5a20: 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74  umber()], [sqlit
5a30: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a  e3_sourceid()],.
5a40: 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69  ** [sqlite_versi
5a50: 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
5a60: 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a  e_source_id()]..
5a70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a80: 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20  E_VERSION       
5a90: 20 22 33 2e 37 2e 39 22 0a 23 64 65 66 69 6e 65   "3.7.9".#define
5aa0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
5ab0: 4e 55 4d 42 45 52 20 33 30 30 37 30 30 39 0a 23  NUMBER 3007009.#
5ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f  define SQLITE_SO
5ad0: 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 32 30  URCE_ID      "20
5ae0: 31 31 2d 31 31 2d 30 38 20 31 35 3a 30 36 3a 30  11-11-08 15:06:0
5af0: 35 20 61 34 39 39 61 65 33 38 33 35 65 64 37 66  5 a499ae3835ed7f
5b00: 31 35 39 31 63 34 30 62 65 61 32 30 65 30 63 39  1591c40bea20e0c9
5b10: 37 66 35 38 63 65 65 64 62 62 22 0a 0a 2f 2a 0a  7f58ceedbb"../*.
5b20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
5b30: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
5b40: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
5b50: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
5b60: 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69  e3_version, sqli
5b70: 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a  te3_sourceid.**.
5b80: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
5b90: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
5ba0: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
5bb0: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
5bc0: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
5bd0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
5be0: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
5bf0: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
5c00: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
5c10: 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73  os.** but are as
5c20: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
5c30: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61  e library instea
5c40: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20  d of the header 
5c50: 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75  file.  ^(Cautiou
5c60: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
5c70: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
5c80: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
5c90: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
5ca0: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
5cb0: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
5cc0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
5cd0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
5ce0: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
5cf0: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
5d00: 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65   and thus insure
5d10: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
5d20: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
5d30: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
5d40: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
5d50: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
5d60: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
5d70: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
5d80: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
5d90: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
5da0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
5db0: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
5dc0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
5dd0: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
5de0: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
5df0: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
5e00: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
5e10: 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45  version(),SQLITE
5e20: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a  _VERSION)==0 );.
5e30: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
5e40: 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
5e50: 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  The sqlite3_vers
5e60: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
5e70: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74  stant contains t
5e80: 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49  he text of [SQLI
5e90: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d  TE_VERSION].** m
5ea0: 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  acro.  ^The sqli
5eb0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
5ec0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
5ed0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
5ee0: 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c  he.** to the sql
5ef0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
5f00: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
5f10: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
5f20: 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e  version().** fun
5f30: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
5f40: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c  d for use in DLL
5f50: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72  s since DLL user
5f60: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  s usually do not
5f70: 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20   have.** direct 
5f80: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
5f90: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69   constants withi
5fa0: 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65  n the DLL.  ^The
5fb0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  .** sqlite3_libv
5fc0: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20  ersion_number() 
5fd0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
5fe0: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61   an integer equa
5ff0: 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  l to.** [SQLITE_
6000: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
6010: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
6020: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
6030: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
6040: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
6050: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
6060: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
6070: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
6080: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
6090: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
60a0: 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  or macro..**.** 
60b0: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
60c0: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  e_version()] and
60d0: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f   [sqlite_source_
60e0: 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  id()]..*/.SQLITE
60f0: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
6100: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
6110: 5d 20 3d 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ] = SQLITE_VERSI
6120: 4f 4e 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  ON;.SQLITE_API c
6130: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
6140: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f  e3_libversion(vo
6150: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
6160: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
6170: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69  te3_sourceid(voi
6180: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
6190: 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  nt sqlite3_libve
61a0: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69  rsion_number(voi
61b0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
61c0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
61d0: 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f  brary Compilatio
61e0: 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f  n Options Diagno
61f0: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stics.**.** ^The
6200: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
6210: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75  option_used() fu
6220: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30  nction returns 0
6230: 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61   or 1 .** indica
6240: 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65  ting whether the
6250: 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f   specified optio
6260: 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74  n was defined at
6270: 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d   .** compile tim
6280: 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  e.  ^The SQLITE_
6290: 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f   prefix may be o
62a0: 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
62b0: 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20  .** option name 
62c0: 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65  passed to sqlite
62d0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
62e0: 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20  used().  .**.** 
62f0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
6300: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
6310: 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73   function allows
6320: 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76   iterating.** ov
6330: 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f  er the list of o
6340: 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65  ptions that were
6350: 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70   defined at comp
6360: 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72  ile time by.** r
6370: 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74  eturning the N-t
6380: 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f  h compile time o
6390: 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e  ption string.  ^
63a0: 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  If N is out of r
63b0: 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ange,.** sqlite3
63c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
63d0: 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  et() returns a N
63e0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
63f0: 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70  he SQLITE_ .** p
6400: 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64  refix is omitted
6410: 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67   from any string
6420: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a  s returned by .*
6430: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
6440: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a  eoption_get()..*
6450: 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f  *.** ^Support fo
6460: 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63  r the diagnostic
6470: 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74   functions sqlit
6480: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
6490: 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73  _used().** and s
64a0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
64b0: 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62  tion_get() may b
64c0: 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65  e omitted by spe
64d0: 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20  cifying the .** 
64e0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d  [SQLITE_OMIT_COM
64f0: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
6500: 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70  ] option at comp
6510: 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile time..**.** 
6520: 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75  See also: SQL fu
6530: 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f  nctions [sqlite_
6540: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
6550: 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
6560: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  lite_compileopti
6570: 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68  on_get()] and th
6580: 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f  e [compile_optio
6590: 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23  ns pragma]..*/.#
65a0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
65b0: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e  IT_COMPILEOPTION
65c0: 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50  _DIAGS.SQLITE_AP
65d0: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
65e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
65f0: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70  (const char *zOp
6600: 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41  tName);.SQLITE_A
6610: 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
6620: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
6630: 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b  tion_get(int N);
6640: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
6650: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
6660: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
6670: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
6680: 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
6690: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
66a0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
66b0: 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f  ns zero if and o
66c0: 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65  nly if.** SQLite
66d0: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 6d 75   was compiled mu
66e0: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
66f0: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
6700: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
6710: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
6720: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
6730: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
6740: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
6750: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
6760: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
6770: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
6780: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
6790: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
67a0: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
67b0: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
67c0: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
67d0: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
67e0: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
67f0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
6800: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
6810: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
6820: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
6830: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
6840: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
6850: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
6860: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
6870: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
6880: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
6890: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
68a0: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
68b0: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
68c0: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
68d0: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
68e0: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
68f0: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
6900: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
6910: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
6920: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
6930: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
6940: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
6950: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
6960: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
6970: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
6980: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
6990: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
69a0: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
69b0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
69c0: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
69d0: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
69e0: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
69f0: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
6a00: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
6a10: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
6a20: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
6a30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
6a40: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
6a50: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
6a60: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
6a70: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
6a80: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
6a90: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
6aa0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
6ab0: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
6ac0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
6ad0: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
6ae0: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
6af0: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
6b00: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
6b10: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
6b20: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
6b30: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
6b40: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
6b50: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
6b60: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
6b70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
6b80: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
6b90: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
6ba0: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
6bb0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
6bc0: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
6bd0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
6be0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
6bf0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
6c00: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
6c10: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
6c20: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
6c30: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
6c40: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
6c50: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
6c60: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
6c70: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
6c80: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
6c90: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
6ca0: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
6cb0: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
6cc0: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
6cd0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
6ce0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
6cf0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
6d00: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
6d10: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
6d20: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
6d30: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
6d40: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
6d50: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
6d60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
6d70: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
6d80: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
6d90: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
6da0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
6db0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
6dc0: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
6dd0: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
6de0: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
6df0: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
6e00: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
6e10: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
6e20: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
6e30: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
6e40: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
6e50: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
6e60: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
6e70: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
6e80: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
6e90: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
6ea0: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
6eb0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6ec0: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
6ed0: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
6ee0: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
6ef0: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 20  _close()].** is 
6f00: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20  its destructor. 
6f10: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
6f20: 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  other interfaces
6f30: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
6f40: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
6f50: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
6f60: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
6f70: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
6f80: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
6f90: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
6fa0: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
6fb0: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
6fc0: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
6fd0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
6fe0: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
6ff0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7000: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
7010: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
7020: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
7030: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
7040: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
7050: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
7060: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
7070: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
7080: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
7090: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
70a0: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
70b0: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
70c0: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
70d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
70e0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
70f0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
7100: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
7110: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
7120: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
7130: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
7140: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
7150: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
7160: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
7170: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
7180: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
7190: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
71a0: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
71b0: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
71c0: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
71d0: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
71e0: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
71f0: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
7200: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
7210: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
7220: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
7230: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
7240: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
7250: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
7260: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
7270: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
7280: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
7290: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
72a0: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
72b0: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
72c0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
72d0: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
72e0: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
72f0: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
7300: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
7310: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
7320: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
7330: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
7340: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
7350: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
7360: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
7370: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
7380: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
7390: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
73a0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
73b0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
73c0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
73d0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
73e0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
73f0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
7400: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
7410: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
7420: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
7430: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
7440: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
7450: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
7460: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
7470: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
7480: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
7490: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
74a0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
74b0: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
74c0: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
74d0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
74e0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
74f0: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
7500: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
7510: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
7520: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
7530: 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64  routine is the d
7540: 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
7550: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
7560: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
7570: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
7580: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
7590: 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  K if the [sqlite
75a0: 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  3] object is.** 
75b0: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73  successfully des
75c0: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61  troyed and all a
75d0: 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75 72  ssociated resour
75e0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
75f0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ted..**.** Appli
7600: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73 71  cations must [sq
7610: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
7620: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b   finalize] all [
7630: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
7640: 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  nts].** and [sql
7650: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
7660: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
7670: 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f  OB handles] asso
7680: 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74  ciated with.** t
7690: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
76a0: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74  ect prior to att
76b0: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65  empting to close
76c0: 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49   the object.  ^I
76d0: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f  f.** sqlite3_clo
76e0: 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  se() is called o
76f0: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
7700: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
7710: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
7720: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
7730: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f 72  d statements] or
7740: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
7750: 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73   then it returns
7760: 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  .** SQLITE_BUSY.
7770: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c 69  .**.** ^If [sqli
7780: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
7790: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
77a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
77b0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
77c0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
77d0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
77e0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
77f0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
7800: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
7810: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
7820: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
7830: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
7840: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
7850: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
7860: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
7870: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
7880: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
7890: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
78a0: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
78b0: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
78c0: 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
78d0: 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68 20  e3_close() with 
78e0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
78f0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a 2a  rgument is a .**
7900: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
7910: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
7920: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
7930: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
7940: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
7950: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
7960: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
7970: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
7980: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
7990: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
79a0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
79b0: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
79c0: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
79d0: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
79e0: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
79f0: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
7a00: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
7a10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
7a20: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
7a30: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
7a40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
7a50: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
7a60: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
7a70: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
7a80: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
7a90: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
7aa0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
7ab0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
7ac0: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
7ad0: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
7ae0: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
7af0: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
7b00: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
7b10: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
7b20: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
7b30: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
7b40: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
7b50: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
7b60: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
7b70: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
7b80: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
7b90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
7ba0: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
7bb0: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
7bc0: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
7bd0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
7be0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
7bf0: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
7c00: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
7c10: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
7c20: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
7c30: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
7c40: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
7c50: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
7c60: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
7c70: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
7c80: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
7c90: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
7ca0: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
7cb0: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
7cc0: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
7cd0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
7ce0: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
7cf0: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
7d00: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
7d10: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
7d20: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
7d30: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
7d40: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
7d50: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
7d60: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
7d70: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
7d80: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
7d90: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
7da0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
7db0: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
7dc0: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
7dd0: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
7de0: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
7df0: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
7e00: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
7e10: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
7e20: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
7e30: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
7e40: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
7e50: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
7e60: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
7e70: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
7e80: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
7e90: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
7ea0: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
7eb0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
7ec0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
7ed0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
7ee0: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
7ef0: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
7f00: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
7f10: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
7f20: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
7f30: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
7f40: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
7f50: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
7f60: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
7f70: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
7f80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
7f90: 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  of.** of sqlite3
7fa0: 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68  _exec() after th
7fb0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
7fc0: 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e  string is no lon
7fd0: 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e  ger needed..** ^
7fe0: 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  If the 5th param
7ff0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
8000: 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55  exec() is not NU
8010: 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73  LL and no errors
8020: 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20  .** occur, then 
8030: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73  sqlite3_exec() s
8040: 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ets the pointer 
8050: 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d  in its 5th param
8060: 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20  eter to.** NULL 
8070: 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
8080: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73  ..**.** ^If an s
8090: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
80a0: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
80b0: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c  on-zero, the sql
80c0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72  ite3_exec().** r
80d0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53  outine returns S
80e0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68  QLITE_ABORT with
80f0: 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  out invoking the
8100: 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20   callback again 
8110: 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72  and.** without r
8120: 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65  unning any subse
8130: 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d  quent SQL statem
8140: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
8150: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   2nd argument to
8160: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
8170: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  c() callback fun
8180: 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20  ction is the.** 
8190: 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
81a0: 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e  s in the result.
81b0: 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d    ^The 3rd argum
81c0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
81d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c  e3_exec().** cal
81e0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
81f0: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
8200: 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65   strings obtaine
8210: 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20  d as if from.** 
8220: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
8230: 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72  text()], one for
8240: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e   each column.  ^
8250: 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66  If an element of
8260: 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77   a.** result row
8270: 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
8280: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
8290: 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66  string pointer f
82a0: 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  or the.** sqlite
82b0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
82c0: 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  k is a NULL poin
82d0: 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61  ter.  ^The 4th a
82e0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
82f0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
8300: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
8310: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
8320: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65  s to strings whe
8330: 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79  re each.** entry
8340: 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20   represents the 
8350: 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f  name of correspo
8360: 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c  nding result col
8370: 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a  umn as obtained.
8380: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
8390: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e  _column_name()].
83a0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32  .**.** ^If the 2
83b0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
83c0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
83d0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
83e0: 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  , a pointer.** t
83f0: 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
8400: 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  g, or a pointer 
8410: 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e  that contains on
8420: 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e  ly whitespace an
8430: 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d  d/or .** SQL com
8440: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53  ments, then no S
8450: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
8460: 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20  e evaluated and 
8470: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8480: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a  is not changed..
8490: 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f  **.** Restrictio
84a0: 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ns:.**.** <ul>.*
84b0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
84c0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75  cation must insu
84d0: 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20  re that the 1st 
84e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
84f0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20  ite3_exec().**  
8500: 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61      is a valid a
8510: 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  nd open [databas
8520: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
8530: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
8540: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
8550: 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20  close [database 
8560: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
8570: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
8580: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
8590: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
85a0: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
85b0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
85c0: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
85d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
85e0: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
85f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
8600: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
8610: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
8620: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
8630: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
8640: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
8650: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
8660: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
8670: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
8680: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
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 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
86c0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
86d0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
86e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
86f0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
8700: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
8710: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
8720: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
8730: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
8740: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
8750: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
8760: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8770: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8780: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
8790: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
87a0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
87b0: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
87c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
87d0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
87e0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
87f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8800: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
8810: 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
8820: 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65  E_OK {error code
8830: 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  } {error codes}.
8840: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65  ** KEYWORDS: {re
8850: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75  sult code} {resu
8860: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
8870: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
8880: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
8890: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
88a0: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
88b0: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
88c0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
88d0: 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20  ates success or 
88e0: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
88f0: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
8900: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
8910: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
8920: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
8930: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
8940: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
8950: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
8960: 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  odes],.** [sqlit
8970: 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
8980: 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52  ict()] [SQLITE_R
8990: 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74  OLLBACK | result
89a0: 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66   codes]..*/.#def
89b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
89c0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
89d0: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
89e0: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
89f0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
8a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8a10: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
8a20: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
8a30: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
8a40: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
8a50: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
8a60: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
8a70: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
8a80: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
8a90: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
8aa0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
8ab0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
8ac0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
8ad0: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
8ae0: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
8af0: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
8b00: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
8b10: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
8b20: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
8b30: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
8b40: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
8b50: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
8b60: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
8b70: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
8b80: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
8b90: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
8ba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
8bb0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
8bc0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
8bd0: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
8be0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
8bf0: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
8c00: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
8c10: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
8c20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8c30: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
8c40: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
8c50: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
8c60: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
8c70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8c80: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
8c90: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
8ca0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
8cb0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
8cc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
8cd0: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
8ce0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
8cf0: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
8d00: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
8d10: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
8d20: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
8d30: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
8d40: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8d50: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
8d60: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
8d70: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
8d80: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
8d90: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
8da0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
8db0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
8dc0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
8dd0: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
8de0: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
8df0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
8e00: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
8e10: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
8e20: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
8e30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8e40: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
8e50: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
8e60: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
8e70: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
8e80: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
8e90: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
8ea0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
8eb0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
8ec0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
8ed0: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
8ee0: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
8ef0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8f00: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
8f10: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
8f20: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
8f30: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
8f40: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
8f50: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
8f60: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
8f70: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
8f80: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
8f90: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
8fa0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
8fb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8fc0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
8fd0: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
8fe0: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
8ff0: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
9000: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9010: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
9020: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
9030: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
9040: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
9050: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
9060: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
9070: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
9080: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9090: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
90a0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
90b0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
90c0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
90d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
90e0: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
90f0: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
9100: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
9110: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
9120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9130: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
9140: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
9150: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
9160: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
9170: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
9180: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
9190: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
91a0: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
91b0: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
91c0: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
91d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
91e0: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
91f0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
9200: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65  RDS: {extended e
9210: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65  rror code} {exte
9220: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
9230: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
9240: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
9250: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
9260: 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a  result codes}.**
9270: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
9280: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
9290: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
92a0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
92b0: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a   of 26 integer.*
92c0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72  * [SQLITE_OK | r
92d0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
92e0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
92f0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
9300: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
9310: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
9320: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
9330: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
9340: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
9350: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
9360: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
9370: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
9380: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
9390: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
93a0: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
93b0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
93c0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
93d0: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65  n 3.3.8 and late
93e0: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
93f0: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
9400: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
9410: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
9420: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
9430: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
9440: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78  t errors. The ex
9450: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
9460: 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  des are enabled 
9470: 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f  or disabled.** o
9480: 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65  n a per database
9490: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
94a0: 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  s using the.** [
94b0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
94c0: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
94d0: 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65   API..**.** Some
94e0: 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c   of the availabl
94f0: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
9500: 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74  t codes are list
9510: 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20  ed here..** One 
9520: 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e  may expect the n
9530: 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65  umber of extende
9540: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77  d result codes w
9550: 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a  ill be expand.**
9560: 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66   over time.  Sof
9570: 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20  tware that uses 
9580: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
9590: 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70  codes should exp
95a0: 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65  ect.** to see ne
95b0: 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69  w result codes i
95c0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
95d0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
95e0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b  ** The SQLITE_OK
95f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c   result code wil
9600: 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e  l never be exten
9610: 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c  ded.  It will al
9620: 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74  ways.** be exact
9630: 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66  ly zero..*/.#def
9640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
9650: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
9660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
9670: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
9680: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
9690: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
96a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
96b0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
96c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
96d0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
96e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
96f0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
9700: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
9710: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
9720: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9730: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
9740: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
9750: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
9760: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9770: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
9780: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
9790: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
97a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
97b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
97c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
97d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
97e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
97f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9800: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
9810: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9820: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
9830: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
9840: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
9850: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
9860: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
9870: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9880: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
9890: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
98a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
98b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
98c0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
98d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
98e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
98f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9900: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
9910: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9920: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
9930: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9940: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
9950: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9960: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
9970: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9980: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
9990: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
99a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
99b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
99c0: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
99d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
99e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
99f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9a00: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
9a10: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9a20: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
9a30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9a40: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
9a50: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
9a60: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
9a70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9a80: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
9a90: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9aa0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
9ab0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9ac0: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
9ad0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9ae0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
9af0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9b00: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
9b10: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9b20: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
9b30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9b40: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
9b50: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9b60: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
9b70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9b80: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
9b90: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9ba0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
9bb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9bc0: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
9bd0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
9be0: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
9bf0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
9c00: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59  TE_BUSY_RECOVERY
9c10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
9c20: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c  TE_BUSY   |  (1<
9c30: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9c40: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
9c50: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
9c60: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
9c70: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
9c80: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
9c90: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
9ca0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
9cb0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
9cc0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
9cd0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
9ce0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
9cf0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
9d00: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
9d10: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
9d20: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
9d30: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a  Y | (2<<8))../*.
9d40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
9d50: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
9d60: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
9d70: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
9d80: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
9d90: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
9da0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
9db0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
9dc0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
9dd0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
9de0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
9df0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9e00: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
9e10: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
9e20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
9e30: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
9e40: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
9e50: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
9e60: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
9e70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
9e80: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
9e90: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
9ea0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
9eb0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
9ec0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
9ed0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
9ee0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
9ef0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
9f00: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
9f10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
9f20: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
9f30: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
9f40: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
9f50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
9f60: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
9f70: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
9f80: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
9f90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
9fa0: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
9fb0: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
9fc0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
9fd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
9fe0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
9ff0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
a000: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
a010: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
a020: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
a030: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
a040: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
a050: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
a060: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
a070: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
a080: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
a090: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
a0a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
a0b0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
a0c0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
a0d0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
a0e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
a0f0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
a100: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
a110: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
a120: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
a130: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
a140: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
a150: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
a160: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
a170: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
a180: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
a190: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
a1a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
a1b0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
a1c0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
a1d0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
a1e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
a1f0: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
a200: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
a210: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
a220: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
a230: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
a240: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
a250: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
a260: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
a270: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
a280: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
a290: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
a2a0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
a2b0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
a2c0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
a2d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
a2e0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
a2f0: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
a300: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
a310: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
a320: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
a330: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
a340: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
a350: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
a360: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
a370: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
a380: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
a390: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
a3a0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
a3b0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
a3c0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
a3d0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
a3e0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
a3f0: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
a400: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
a410: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
a420: 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65  ector of the the
a430: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
a440: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
a450: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
a460: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
a470: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
a480: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
a490: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
a4a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
a4b0: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
a4c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
a4d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
a4e0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
a4f0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
a500: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
a510: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
a520: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
a530: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
a540: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
a550: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
a560: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
a570: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
a580: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
a590: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
a5a0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
a5b0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
a5c0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
a5d0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
a5e0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
a5f0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
a600: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
a610: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
a620: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
a630: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
a640: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
a650: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
a660: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
a670: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
a680: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
a690: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
a6a0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
a6b0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
a6c0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
a6d0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
a6e0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
a6f0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64   xWrite()..*/.#d
a700: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
a710: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
a720: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
a730: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
a740: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a750: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
a760: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
a770: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
a780: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
a790: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a7a0: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
a7b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
a7c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
a7d0: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
a7e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
a7f0: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
a800: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
a810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a820: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
a830: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
a840: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
a850: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a860: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
a870: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
a880: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
a890: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
a8a0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
a8b0: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
a8c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a8d0: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
a8e0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
a8f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
a900: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
a910: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
a920: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
a930: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
a940: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
a950: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
a960: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
a970: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
a980: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
a990: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
a9a0: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
a9b0: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  Levels.**.** SQL
a9c0: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
a9d0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
a9e0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
a9f0: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
aa00: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
aa10: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
aa20: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
aa30: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
aa40: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
aa50: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
aa60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
aa70: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
aa80: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
aa90: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
aaa0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
aab0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
aac0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
aad0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
aae0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
aaf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
ab00: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
ab10: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
ab20: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
ab30: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a  ion Type Flags.*
ab40: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
ab50: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
ab60: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
ab70: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
ab80: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
ab90: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
aba0: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  nation of.** the
abb0: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
abc0: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
abd0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
abe0: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
abf0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
ac00: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
ac10: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
ac20: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
ac30: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
ac40: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
ac50: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
ac60: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
ac70: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
ac80: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65  hed. If the lowe
ac90: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74  r four bits of t
aca0: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c  he flag.** equal
acb0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
acc0: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  MAL, that means 
acd0: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
ace0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
acf0: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72  .** If the lower
ad00: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c   four bits equal
ad10: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
ad20: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  L, that means.**
ad30: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58   to use Mac OS X
ad40: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
ad50: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
ad60: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74  ()..**.** Do not
ad70: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c   confuse the SQL
ad80: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
ad90: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
ada0: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69  FULL flags.** wi
adb0: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73  th the [PRAGMA s
adc0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d  ynchronous]=NORM
add0: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73  AL and [PRAGMA s
ade0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c  ynchronous]=FULL
adf0: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54  .** settings.  T
ae00: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20  he [synchronous 
ae10: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e  pragma] determin
ae20: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f  es when calls to
ae30: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46   the.** xSync VF
ae40: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61  S method occur a
ae50: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f  nd applies unifo
ae60: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  rmly across all 
ae70: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68  platforms..** Th
ae80: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
ae90: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
aea0: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20  SYNC_FULL flags 
aeb0: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a  determine how.**
aec0: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69   energetic or ri
aed0: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66  gorous or forcef
aee0: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72  ul the sync oper
aef0: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a  ations are and.*
af00: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69  * only make a di
af10: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20  fference on Mac 
af20: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61  OSX for the defa
af30: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e  ult SQLite code.
af40: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79  .** (Third-party
af50: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
af60: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  ions might also 
af70: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
af80: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
af90: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
afa0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
afb0: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f  NC_FULL, but amo
afc0: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74  ng the.** operat
afd0: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69  ing systems nati
afe0: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62  vely supported b
aff0: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d  y SQLite, only M
b000: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20  ac OSX.** cares 
b010: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72  about the differ
b020: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e  ence.).*/.#defin
b030: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
b040: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30  RMAL        0x00
b050: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
b060: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20  TE_SYNC_FULL    
b070: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64        0x00003.#d
b080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
b090: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20  C_DATAONLY      
b0a0: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43  0x00010../*.** C
b0b0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
b0c0: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20  rface Open File 
b0d0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20  Handle.**.** An 
b0e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
b0f0: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
b100: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
b110: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
b120: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72  3_vfs | OS inter
b130: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e  face layer].  In
b140: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
b150: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  rface.** impleme
b160: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
b170: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
b180: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
b190: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
b1a0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
b1b0: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73  for their own us
b1c0: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
b1d0: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
b1e0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
b1f0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
b200: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
b210: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
b220: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
b230: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
b240: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
b250: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
b260: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
b270: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
b280: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
b290: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
b2a0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
b2b0: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
b2c0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
b2d0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
b2e0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
b2f0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
b300: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
b310: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
b320: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
b330: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
b340: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
b350: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
b360: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
b370: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
b380: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
b390: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
b3a0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
b3b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
b3c0: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
b3d0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
b3e0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
b3f0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
b400: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
b410: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
b420: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
b430: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
b440: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
b450: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
b460: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
b470: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
b480: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
b490: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74  Open] method set
b4a0: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  s the sqlite3_fi
b4b0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
b4c0: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e  ent .** to a non
b4d0: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
b4e0: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
b4f0: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73  io_methods.xClos
b500: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20  e method.** may 
b510: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20  be invoked even 
b520: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  if the [sqlite3_
b530: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72  vfs.xOpen] repor
b540: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
b550: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
b560: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
b570: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
b580: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
b590: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  led [sqlite3_vfs
b5a0: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f  .xOpen].** is fo
b5b0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  r the [sqlite3_v
b5c0: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74  fs.xOpen] to set
b5d0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
b5e0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
b5f0: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  nt.** to NULL..*
b600: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
b610: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
b620: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
b630: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
b640: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
b650: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
b660: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
b670: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
b680: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ync()..** The se
b690: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
b6a0: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
b6b0: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b  fullsync.  The [
b6c0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
b6d0: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61  ONLY].** flag ma
b6e0: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20  y be ORed in to 
b6f0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
b700: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
b710: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e  he file.** and n
b720: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65  ot its inode nee
b730: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e  ds to be synced.
b740: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67  .**.** The integ
b750: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f  er values to xLo
b760: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
b770: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a  () are one of.**
b780: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
b790: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
b7a0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
b7b0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
b7c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
b7d0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a  LOCK_RESERVED],.
b7e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
b7f0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
b800: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
b810: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
b820: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78  ]..** </ul>.** x
b830: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73  Lock() increases
b840: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f   the lock. xUnlo
b850: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74  ck() decreases t
b860: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20  he lock..** The 
b870: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
b880: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63  ck() method chec
b890: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64  ks whether any d
b8a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
b8b0: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e  on,.** either in
b8c0: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72   this process or
b8d0: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
b8e0: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
b8f0: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a  ng a RESERVED,.*
b900: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
b910: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
b920: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
b930: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
b940: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
b950: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74  sts and false ot
b960: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54  herwise..**.** T
b970: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
b980: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
b990: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
b9a0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
b9b0: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
b9c0: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
b9d0: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
b9e0: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
b9f0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
ba00: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
ba10: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
ba20: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
ba30: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69  ument is an.** i
ba40: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
ba50: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
ba60: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  nt is a generic 
ba70: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64  pointer intended
ba80: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20   to.** point to 
ba90: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  a structure that
baa0: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67   may contain arg
bab0: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20  uments or space 
bac0: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77  in which to.** w
bad0: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75  rite return valu
bae0: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75  es.  Potential u
baf0: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e  ses for xFileCon
bb00: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a  trol() might be.
bb10: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ** functions to 
bb20: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20  enable blocking 
bb30: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f  locks with timeo
bb40: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74  uts, to change t
bb50: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74  he.** locking st
bb60: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d  rategy (for exam
bb70: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66  ple to use dot-f
bb80: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69  ile locks), to i
bb90: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20  nquire.** about 
bba0: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20  the status of a 
bbb0: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61  lock, or to brea
bbc0: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20  k stale locks.  
bbd0: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f  The SQLite.** co
bbe0: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20  re reserves all 
bbf0: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
bc00: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
bc10: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c  n use..** A [SQL
bc20: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
bc30: 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  ATE | list of op
bc40: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
bc50: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
bc60: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
bc70: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
bc80: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
bc90: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
bca0: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
bcb0: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
bcc0: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
bcd0: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
bce0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
bcf0: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
bd00: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
bd10: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
bd20: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
bd30: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
bd40: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
bd50: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
bd60: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
bd70: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
bd80: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
bd90: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
bda0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
bdb0: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
bdc0: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
bdd0: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
bde0: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
bdf0: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
be00: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
be10: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
be20: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
be30: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
be40: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
be50: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
be60: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
be70: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
be80: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
be90: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
bea0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
beb0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
bec0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
bed0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
bee0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
bef0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
bf00: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
bf10: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
bf20: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
bf30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
bf40: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
bf50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
bf60: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
bf70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
bf80: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
bf90: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
bfa0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
bfb0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
bfc0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
bfd0: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
bfe0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
bff0: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  NTIAL].** </ul>.
c000: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
c010: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
c020: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
c030: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
c040: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
c050: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
c060: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
c070: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
c080: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
c090: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
c0a0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
c0b0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
c0c0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
c0d0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
c0e0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
c0f0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
c100: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
c110: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
c120: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
c130: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
c140: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
c150: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
c160: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
c170: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
c180: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
c190: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
c1a0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
c1b0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
c1c0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
c1d0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
c1e0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
c1f0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
c200: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
c210: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
c220: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
c230: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a  to xWrite()..**.
c240: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65  ** If xRead() re
c250: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45  turns SQLITE_IOE
c260: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74  RR_SHORT_READ it
c270: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a   must also fill.
c280: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64  ** in the unread
c290: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65   portions of the
c2a0: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72   buffer with zer
c2b0: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a  os.  A VFS that.
c2c0: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f  ** fails to zero
c2d0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
c2e0: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20  s might seem to 
c2f0: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a  work.  However,.
c300: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65  ** failure to ze
c310: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
c320: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ads will eventua
c330: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64  lly lead to.** d
c340: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
c350: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
c360: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
c370: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
c380: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
c390: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
c3a0: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
c3b0: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
c3c0: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
c3d0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
c3e0: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
c3f0: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
c400: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
c410: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
c420: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
c430: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
c440: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
c450: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
c460: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
c470: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
c480: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
c490: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
c4a0: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
c4b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
c4c0: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
c4d0: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
c4e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
c4f0: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
c500: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
c510: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
c520: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
c530: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
c540: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
c550: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
c560: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
c570: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
c580: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
c590: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
c5a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
c5b0: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
c5c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
c5d0: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
c5e0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
c5f0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
c600: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
c610: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  ile*);.  /* Meth
c620: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
c630: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
c640: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68  1 */.  int (*xSh
c650: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  mMap)(sqlite3_fi
c660: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e  le*, int iPg, in
c670: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
c680: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
c690: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
c6a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
c6b0: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20  int offset, int 
c6c0: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  n, int flags);. 
c6d0: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72   void (*xShmBarr
c6e0: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ier)(sqlite3_fil
c6f0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
c700: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f  mUnmap)(sqlite3_
c710: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74  file*, int delet
c720: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74  eFlag);.  /* Met
c730: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
c740: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
c750: 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74   2 */.  /* Addit
c760: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
c770: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
c780: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
c790: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
c7a0: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
c7b0: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
c7c0: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  es.**.** These i
c7d0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
c7e0: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72   are opcodes for
c7f0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
c800: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  l method.** of t
c810: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
c820: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
c830: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  nd for the [sqli
c840: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
c850: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
c860: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
c870: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
c880: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
c890: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
c8a0: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
c8b0: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
c8c0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
c8d0: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
c8e0: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
c8f0: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
c900: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
c910: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
c920: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
c930: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
c940: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
c950: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
c960: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
c970: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
c980: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
c990: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
c9a0: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
c9b0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
c9c0: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
c9d0: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f  ng testing and o
c9e0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
c9f0: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
ca00: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73  QLITE_TEST.** is
ca10: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
ca20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ca30: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63  L_SIZE_HINT] opc
ca40: 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53  ode is used by S
ca50: 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68  QLite to give th
ca60: 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61  e VFS.** layer a
ca70: 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72   hint of how lar
ca80: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
ca90: 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74  file will grow t
caa0: 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a  o be during the.
cab0: 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  ** current trans
cac0: 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69  action.  This hi
cad0: 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e  nt is not guaran
cae0: 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72  teed to be accur
caf0: 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73  ate but it.** is
cb00: 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54   often close.  T
cb10: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46  he underlying VF
cb20: 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74  S might choose t
cb30: 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61  o preallocate da
cb40: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73  tabase.** file s
cb50: 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68  pace based on th
cb60: 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72  is hint in order
cb70: 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20   to help writes 
cb80: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
cb90: 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74  ** file run fast
cba0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  er..**.** The [S
cbb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
cbc0: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
cbd0: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
cbe0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
cbf0: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
cc00: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
cc10: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
cc20: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
cc30: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
cc40: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
cc50: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
cc60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
cc70: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
cc80: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
cc90: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
cca0: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
ccb0: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
ccc0: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
ccd0: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
cce0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
ccf0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
cd00: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
cd10: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
cd20: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
cd30: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
cd40: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
cd50: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
cd60: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
cd70: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
cd80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
cd90: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
cda0: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
cdb0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
cdc0: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
cdd0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
cde0: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
cdf0: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  d with a particu
ce00: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
ce10: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
ce20: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ce30: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f  le_control()] do
ce40: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  cumentation for.
ce50: 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
ce60: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
ce70: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46   ^(The [SQLITE_F
ce80: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
ce90: 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  D] opcode is gen
cea0: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
ceb0: 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61  y by.** SQLite a
cec0: 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56  nd sent to all V
ced0: 46 53 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66  FSes in place of
cee0: 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78   a call to the x
cef0: 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77  Sync method.** w
cf00: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
cf10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20   connection has 
cf20: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
cf30: 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e  ous] set to OFF.
cf40: 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69  )^.** Some speci
cf50: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65  alized VFSes nee
cf60: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e  d this signal in
cf70: 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74   order to operat
cf80: 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77  e correctly.** w
cf90: 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  hen [PRAGMA sync
cfa0: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
cfb0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
cfc0: 5d 20 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f  ] is set, but mo
cfd0: 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20  st .** VFSes do 
cfe0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
cff0: 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20  gnal and should 
d000: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
d010: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20  this opcode..** 
d020: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
d030: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71  uld not call [sq
d040: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
d050: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a  ol()] with this.
d060: 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  ** opcode as doi
d070: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70  ng so may disrup
d080: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
d090: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
d0a0: 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74  ed VFSes.** that
d0b0: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
d0c0: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51   .**.** ^The [SQ
d0d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
d0e0: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
d0f0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
d100: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
d110: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
d120: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
d130: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
d140: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
d150: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
d160: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
d170: 20 74 6f 20 77 6f 72 6b 20 74 6f 20 70 72 6f 76   to work to prov
d180: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 61  ide robustness a
d190: 67 61 69 6e 73 74 0a 2a 2a 20 61 6e 74 69 2d 76  gainst.** anti-v
d1a0: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
d1b0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
d1c0: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
d1d0: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
d1e0: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
d1f0: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
d200: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
d210: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
d220: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
d230: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
d240: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
d250: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
d260: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
d270: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
d280: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
d290: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
d2a0: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
d2b0: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
d2c0: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 6f 73 65  ode allows those
d2d0: 20 74 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72   to values (10 r
d2e0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
d2f0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
d300: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
d310: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
d320: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
d330: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
d340: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
d350: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
d360: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
d370: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
d380: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
d390: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
d3a0: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
d3b0: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
d3c0: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
d3d0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
d3e0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
d3f0: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
d400: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
d410: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
d420: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
d430: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
d440: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
d450: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
d460: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
d470: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
d480: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
d490: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
d4a0: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
d4b0: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
d4c0: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
d4d0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
d4e0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
d4f0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
d500: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20  TL_PERSIST_WAL] 
d510: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
d520: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
d530: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
d540: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 48   [WAL | Write AH
d550: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67  ead Log] setting
d560: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
d570: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20  he auxiliary.** 
d580: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20  write ahead log 
d590: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
d5a0: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72  y files used for
d5b0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
d5c0: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f  trol.** are auto
d5d0: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
d5e0: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73  d when the lates
d5f0: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  t connection to 
d600: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
d610: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67  closes.  Setting
d620: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
d630: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73  mode causes thos
d640: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69  e files to persi
d650: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73  st after.** clos
d660: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74  e.  Persisting t
d670: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66  he files is usef
d680: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72  ul when other pr
d690: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20  ocesses that do 
d6a0: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74  not.** have writ
d6b0: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20  e permission on 
d6c0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
d6d0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74  ntaining the dat
d6e0: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a  abase file want.
d6f0: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64  ** to read the d
d700: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73  atabase file, as
d710: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61   the WAL and sha
d720: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
d730: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69   must exist.** i
d740: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20  n order for the 
d750: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  database to be r
d760: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f  eadable.  The fo
d770: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
d780: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
d790: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
d7a0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
d7b0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
d7c0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
d7d0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
d7e0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
d7f0: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
d800: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
d810: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  ble persistent.*
d820: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20  * WAL mode.  If 
d830: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
d840: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
d850: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
d860: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41  he current.** WA
d870: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65  L persistence se
d880: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tting..**.** ^Th
d890: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
d8a0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
d8b0: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
d8c0: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
d8d0: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
d8e0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
d8f0: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
d900: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
d910: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
d920: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
d930: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
d940: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
d950: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
d960: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
d970: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
d980: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
d990: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 23 64  perations..*/.#d
d9a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d9b0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
d9c0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
d9d0: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
d9e0: 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64  XYFILE      2.#d
d9f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
da00: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
da10: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
da20: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
da30: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
da40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
da50: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
da60: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
da70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
da80: 5f 53 49 5a 45 20 20 20 20 20 20 20 36 0a 23 64  _SIZE       6.#d
da90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
daa0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
dab0: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
dac0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
dad0: 4f 4d 49 54 54 45 44 20 20 20 20 20 38 0a 23 64  OMITTED     8.#d
dae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
daf0: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
db00: 59 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51  Y   9.#define SQ
db10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
db20: 53 54 5f 57 41 4c 20 20 20 20 20 31 30 0a 23 64  ST_WAL     10.#d
db30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
db40: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
db50: 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     11../*.** CAP
db60: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
db70: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  dle.**.** The mu
db80: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
db90: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
dba0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
dbb0: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
dbc0: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
dbd0: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
dbe0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
dbf0: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
dc00: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
dc10: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
dc20: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
dc30: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
dc40: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
dc50: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
dc60: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
dc70: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
dc80: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
dc90: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
dca0: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
dcb0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
dcc0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
dcd0: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
dce0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
dcf0: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
dd00: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
dd10: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
dd20: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
dd30: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
dd40: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
dd50: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
dd60: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
dd70: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
dd80: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
dd90: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
dda0: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
ddb0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
ddc0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
ddd0: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
dde0: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
ddf0: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
de00: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
de10: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
de20: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
de30: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
de40: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
de50: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
de60: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
de70: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
de80: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
de90: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
dea0: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
deb0: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
dec0: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
ded0: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
dee0: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
def0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
df00: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
df10: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
df20: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
df30: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
df40: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
df50: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
df60: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
df70: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
df80: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
df90: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
dfa0: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
dfb0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
dfc0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
dfd0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
dfe0: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
dff0: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
e000: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
e010: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
e020: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
e030: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
e040: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
e050: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
e060: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
e070: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
e080: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
e090: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
e0a0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
e0b0: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
e0c0: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
e0d0: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
e0e0: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
e0f0: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
e100: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
e110: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
e120: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
e130: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
e140: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
e150: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
e160: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
e170: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
e180: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
e190: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
e1a0: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
e1b0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
e1c0: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
e1d0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
e1e0: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
e1f0: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
e200: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
e210: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
e220: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
e230: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
e240: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
e250: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
e260: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
e270: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
e280: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
e290: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
e2a0: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
e2b0: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
e2c0: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
e2d0: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
e2e0: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
e2f0: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
e300: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
e310: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
e320: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
e330: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
e340: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
e350: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
e360: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
e370: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
e380: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
e390: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
e3a0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
e3b0: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
e3c0: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
e3d0: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
e3e0: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
e3f0: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
e400: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
e410: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
e420: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
e430: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
e440: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
e450: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
e460: 6e 0a 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d  n.** 10 alphanum
e470: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
e480: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
e490: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
e4a0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
e4b0: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
e4c0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
e4d0: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
e4e0: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
e4f0: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
e500: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
e510: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
e520: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
e530: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
e540: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
e550: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
e560: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
e570: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
e580: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
e590: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
e5a0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
e5b0: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
e5c0: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
e5d0: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
e5e0: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
e5f0: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
e600: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
e610: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
e620: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e630: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
e640: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
e650: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
e660: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
e670: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
e680: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
e690: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
e6a0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
e6b0: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
e6c0: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
e6d0: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
e6e0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
e6f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
e700: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
e710: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
e720: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
e730: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
e740: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
e750: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
e760: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
e770: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
e780: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
e790: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
e7a0: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
e7b0: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
e7c0: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
e7d0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
e7e0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
e7f0: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
e800: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
e810: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
e820: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
e830: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
e840: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
e850: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
e860: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
e870: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
e880: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
e890: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
e8a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
e8b0: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
e8c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
e8d0: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
e8e0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e8f0: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
e900: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e910: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
e920: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e930: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
e940: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e950: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
e960: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
e970: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
e980: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
e990: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e9a0: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
e9b0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
e9c0: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
e9d0: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
e9e0: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
e9f0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
ea00: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
ea10: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
ea20: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
ea30: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
ea40: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
ea50: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
ea60: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
ea70: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
ea80: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
ea90: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
eaa0: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
eab0: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
eac0: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
ead0: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
eae0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
eaf0: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
eb00: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
eb10: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
eb20: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
eb30: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
eb40: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
eb50: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
eb60: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
eb70: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
eb80: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
eb90: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
eba0: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
ebb0: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
ebc0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
ebd0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
ebe0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
ebf0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
ec00: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
ec10: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
ec20: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
ec30: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
ec40: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
ec50: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
ec60: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
ec70: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
ec80: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
ec90: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
eca0: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
ecb0: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
ecc0: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
ecd0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
ece0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
ecf0: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
ed00: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
ed10: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
ed20: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
ed30: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
ed40: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
ed50: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
ed60: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
ed70: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
ed80: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
ed90: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
eda0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
edb0: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
edc0: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
edd0: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
ede0: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
edf0: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
ee00: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
ee10: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
ee20: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
ee30: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
ee40: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
ee50: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
ee60: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
ee70: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
ee80: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
ee90: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
eea0: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
eeb0: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
eec0: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
eed0: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
eee0: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
eef0: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
ef00: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
ef10: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
ef20: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
ef30: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
ef40: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
ef50: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
ef60: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
ef70: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
ef80: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
ef90: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
efa0: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
efb0: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
efc0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
efd0: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
efe0: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
eff0: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
f000: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
f010: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
f020: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
f030: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
f040: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
f050: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
f060: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
f070: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
f080: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
f090: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
f0a0: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
f0b0: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
f0c0: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
f0d0: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
f0e0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
f0f0: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
f100: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
f110: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
f120: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
f130: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
f140: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
f150: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
f160: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
f170: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
f180: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
f190: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
f1a0: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
f1b0: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
f1c0: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
f1d0: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
f1e0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
f1f0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
f200: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
f210: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
f220: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
f230: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
f240: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
f250: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
f260: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
f270: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
f280: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
f290: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
f2a0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
f2b0: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
f2c0: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
f2d0: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
f2e0: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
f2f0: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
f300: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
f310: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
f320: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
f330: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
f340: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
f350: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
f360: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
f370: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
f380: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
f390: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
f3a0: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
f3b0: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
f3c0: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
f3d0: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
f3e0: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
f3f0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
f400: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
f410: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
f420: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
f430: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
f440: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
f450: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
f460: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
f470: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
f480: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
f490: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
f4a0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
f4b0: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
f4c0: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
f4d0: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
f4e0: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
f4f0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
f500: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
f510: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
f520: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
f530: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
f540: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
f550: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
f560: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
f570: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
f580: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
f590: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
f5a0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
f5b0: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
f5c0: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
f5d0: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
f5e0: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
f5f0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
f600: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
f610: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
f620: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
f630: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
f640: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
f650: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
f660: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
f670: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
f680: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
f690: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
f6a0: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
f6b0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
f6c0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
f6d0: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
f6e0: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
f6f0: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
f700: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
f710: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
f720: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
f730: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
f740: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
f750: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
f760: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
f770: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
f780: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
f790: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
f7a0: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
f7b0: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
f7c0: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
f7d0: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
f7e0: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
f7f0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
f800: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
f810: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
f820: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
f830: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
f840: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
f850: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
f860: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
f870: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
f880: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
f890: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
f8a0: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
f8b0: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
f8c0: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
f8d0: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
f8e0: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
f8f0: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
f900: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
f910: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
f920: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
f930: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
f940: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
f950: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
f960: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
f970: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
f980: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
f990: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
f9a0: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
f9b0: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
f9c0: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
f9d0: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
f9e0: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
f9f0: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
fa00: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
fa10: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
fa20: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
fa30: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
fa40: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
fa50: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
fa60: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
fa70: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
fa80: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
fa90: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
faa0: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
fab0: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
fac0: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
fad0: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
fae0: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
faf0: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
fb00: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
fb10: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
fb20: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
fb30: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
fb40: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
fb50: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
fb60: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
fb70: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
fb80: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
fb90: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
fba0: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
fbb0: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
fbc0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
fbd0: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
fbe0: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
fbf0: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
fc00: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
fc10: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
fc20: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
fc30: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
fc40: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
fc50: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
fc60: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
fc70: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
fc80: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
fc90: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
fca0: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
fcb0: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
fcc0: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
fcd0: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
fce0: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
fcf0: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
fd00: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
fd10: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
fd20: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
fd30: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
fd40: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
fd50: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
fd60: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
fd70: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
fd80: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
fd90: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
fda0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
fdb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
fdc0: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
fdd0: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
fde0: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
fdf0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
fe00: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
fe10: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
fe20: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
fe30: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
fe40: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
fe50: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
fe60: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
fe70: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
fe80: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
fe90: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
fea0: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
feb0: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
fec0: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
fed0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
fee0: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
fef0: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
ff00: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
ff10: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
ff20: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
ff30: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
ff40: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
ff50: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
ff60: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
ff70: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
ff80: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
ff90: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
ffa0: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
ffb0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
ffc0: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
ffd0: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
ffe0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
fff0: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
10000 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
10010 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
10020 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
10030 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
10040 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
10050 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
10060 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
10070 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
10080 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
10090 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
100a0 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
100b0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
100c0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
100d0 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
100e0 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
100f0 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
10100 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
10110 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
10120 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
10130 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
10140 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
10150 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
10160 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
10170 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
10180 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
10190 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
101a0 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
101b0 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
101c0 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
101d0 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
101e0 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
101f0 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
10200 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
10210 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
10220 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
10230 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
10240 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
10250 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
10260 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
10270 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
10280 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
10290 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
102a0 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
102b0 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
102c0 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
102d0 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
102e0 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
102f0 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
10300 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
10310 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
10320 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
10330 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
10340 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
10350 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
10360 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
10370 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
10380 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
10390 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
103a0 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
103b0 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
103c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
103d0 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
103e0 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
103f0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
10400 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
10410 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
10420 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
10430 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
10440 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
10450 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
10460 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
10470 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
10480 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
10490 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
104a0 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
104b0 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
104c0 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
104d0 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
104e0 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
104f0 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
10500 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
10510 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
10520 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
10530 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
10540 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
10550 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
10560 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
10570 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
10580 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
10590 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
105a0 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
105b0 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
105c0 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
105d0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
105e0 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
105f0 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
10600 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
10610 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
10620 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
10630 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
10640 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
10650 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
10660 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
10670 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
10680 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
10690 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
106a0 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
106b0 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
106c0 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
106d0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
106e0 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
106f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
10700 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
10710 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
10720 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
10730 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
10740 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
10750 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
10760 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
10770 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
10780 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
10790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
107a0 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
107b0 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
107c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
107d0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
107e0 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
107f0 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
10800 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
10810 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
10820 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
10830 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
10840 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
10850 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
10860 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
10870 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
10880 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
10890 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
108a0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
108b0 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
108c0 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
108d0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
108e0 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
108f0 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
10900 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
10910 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
10920 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
10930 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
10940 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
10950 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
10960 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
10970 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
10980 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
10990 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
109a0 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
109b0 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
109c0 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   no the correspo
109d0 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
109e0 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
109f0 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
10a00 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
10a10 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
10a20 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
10a30 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
10a40 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
10a50 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
10a60 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
10a70 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
10a80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10a90 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
10aa0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
10ab0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
10ac0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
10ad0 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
10ae0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
10af0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
10b00 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
10b10 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
10b20 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
10b30 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
10b40 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
10b50 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
10b60 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
10b70 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
10b80 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
10b90 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
10ba0 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
10bb0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
10bc0 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
10bd0 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
10be0 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
10bf0 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
10c00 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
10c10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
10c20 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
10c30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
10c40 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
10c50 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
10c60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
10c70 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10c80 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
10c90 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
10ca0 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
10cb0 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
10cc0 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
10cd0 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
10ce0 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
10cf0 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
10d00 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10d10 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
10d20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
10d30 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
10d40 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
10d50 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
10d60 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
10d70 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
10d80 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
10d90 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
10da0 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
10db0 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
10dc0 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
10dd0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
10de0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
10df0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10e00 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
10e10 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
10e20 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
10e30 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
10e40 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
10e50 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
10e60 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
10e70 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
10e80 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
10e90 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
10ea0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
10eb0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
10ec0 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
10ed0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10ee0 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
10ef0 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
10f00 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
10f10 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
10f20 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
10f30 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
10f40 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
10f50 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
10f60 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
10f70 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
10f80 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
10f90 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
10fa0 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
10fb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
10fc0 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
10fd0 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
10fe0 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
10ff0 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
11000 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
11010 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
11020 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
11030 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
11040 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
11050 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
11060 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
11070 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
11080 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11090 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
110a0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
110b0 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
110c0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
110d0 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
110e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
110f0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
11100 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
11110 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
11120 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
11130 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
11140 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
11150 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
11160 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
11170 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
11180 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
11190 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
111a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
111b0 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
111c0 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
111d0 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
111e0 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
111f0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
11200 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
11210 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
11220 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
11230 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
11240 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
11250 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
11260 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
11270 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
11280 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
11290 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
112a0 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
112b0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
112c0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
112d0 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
112e0 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
112f0 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
11300 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
11310 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
11320 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
11330 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
11340 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
11350 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
11360 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
11370 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11380 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
11390 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
113a0 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
113b0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
113c0 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
113d0 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
113e0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
113f0 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
11400 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11410 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
11420 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
11430 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
11440 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
11450 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
11460 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
11470 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
11480 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
11490 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
114a0 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
114b0 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
114c0 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
114d0 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
114e0 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
114f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11500 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
11510 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
11520 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11530 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
11540 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
11550 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11560 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
11570 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
11580 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
11590 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
115a0 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
115b0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
115c0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
115d0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
115e0 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
115f0 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
11600 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
11610 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
11620 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
11630 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11640 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
11650 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
11660 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
11670 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
11680 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
11690 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
116a0 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
116b0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
116c0 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
116d0 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
116e0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
116f0 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
11700 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
11710 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
11720 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
11730 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
11740 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
11750 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11760 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
11770 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
11780 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
11790 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
117a0 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
117b0 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
117c0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
117d0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
117e0 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
117f0 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
11800 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
11810 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
11820 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
11830 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
11840 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
11850 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
11860 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
11870 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
11880 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
11890 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
118a0 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
118b0 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
118c0 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
118d0 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
118e0 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
118f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11900 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
11910 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
11920 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
11930 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
11940 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
11950 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
11960 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
11970 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
11980 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
11990 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
119a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
119b0 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
119c0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
119d0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
119e0 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
119f0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
11a00 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
11a10 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
11a20 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
11a30 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
11a40 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
11a50 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
11a60 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
11a70 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
11a80 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
11a90 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
11aa0 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
11ab0 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
11ac0 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
11ad0 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
11ae0 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
11af0 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
11b00 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
11b10 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
11b20 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
11b30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
11b40 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
11b50 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
11b60 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
11b70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11b80 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
11b90 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
11ba0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
11bb0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
11bc0 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
11bd0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
11be0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
11bf0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
11c00 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
11c10 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
11c20 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
11c30 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
11c40 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
11c50 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lure..*/.SQLITE_
11c60 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
11c70 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
11c80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
11c90 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11ca0 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  n(void);.SQLITE_
11cb0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
11cc0 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53  os_init(void);.S
11cd0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
11ce0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
11cf0 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
11d00 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
11d10 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
11d20 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
11d30 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
11d40 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
11d50 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
11d60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
11d70 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
11d80 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
11d90 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
11da0 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
11db0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
11dc0 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
11dd0 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
11de0 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
11df0 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
11e00 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
11e10 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
11e20 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
11e30 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
11e40 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
11e50 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
11e60 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
11e70 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
11e80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
11e90 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
11ea0 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
11eb0 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
11ec0 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
11ed0 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
11ee0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
11ef0 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
11f00 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
11f10 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
11f20 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
11f30 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
11f40 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
11f50 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
11f60 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
11f70 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
11f80 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
11f90 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
11fa0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
11fb0 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
11fc0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
11fd0 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
11fe0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11ff0 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
12000 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
12010 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
12020 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
12030 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
12040 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
12050 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
12060 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
12070 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
12080 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
12090 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
120a0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
120b0 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
120c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
120d0 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
120e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
120f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
12100 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
12110 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
12120 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
12130 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
12140 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
12150 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
12160 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
12170 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
12180 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
12190 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
121a0 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
121b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
121c0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
121d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
121e0 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
121f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
12200 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
12210 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
12220 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
12230 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
12240 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
12250 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
12260 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
12270 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
12280 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
12290 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
122a0 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  e]..*/.SQLITE_AP
122b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
122c0 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
122d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
122e0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
122f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
12300 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
12310 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
12320 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
12330 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
12340 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
12350 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
12360 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
12370 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
12380 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
12390 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
123a0 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
123b0 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
123c0 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
123d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
123e0 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
123f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
12400 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent)..**.** The 
12410 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
12420 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
12430 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
12440 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
12450 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
12460 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  IDE | configurat
12470 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69  ion verb] - an i
12480 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20  nteger code .** 
12490 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
124a0 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68  hat aspect of th
124b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
124c0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
124d0 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
124e0 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
124f0 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64  ents vary depend
12500 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69  ing on the confi
12510 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a  guration verb..*
12520 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
12530 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
12540 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
12550 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
12560 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
12570 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
12580 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  cessful..*/.SQLI
12590 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
125a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
125b0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
125c0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
125d0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
125e0 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
125f0 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
12600 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12610 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
12620 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
12630 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
12640 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
12650 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12660 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
12670 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
12680 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
12690 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
126a0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
126b0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
126c0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
126d0 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
126e0 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
126f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
12700 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
12710 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
12720 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12730 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
12740 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12750 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
12760 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
12770 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12780 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
12790 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
127a0 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
127b0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
127c0 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
127d0 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
127e0 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
127f0 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
12800 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
12810 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
12820 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
12830 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
12840 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
12850 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
12860 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
12870 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
12880 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
12890 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
128a0 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
128b0 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
128c0 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
128d0 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
128e0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
128f0 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
12900 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
12910 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
12920 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
12930 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
12940 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
12950 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12960 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
12970 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
12980 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
12990 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
129a0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
129b0 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
129c0 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
129d0 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
129e0 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
129f0 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
12a00 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
12a10 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
12a20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
12a30 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
12a40 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
12a50 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
12a60 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61  he xMalloc, xRea
12a70 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20  lloc, and xFree 
12a80 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
12a90 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
12aa0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
12ab0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
12ac0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
12ad0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
12ae0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  ry..** ^SQLite g
12af0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
12b00 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12b10 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
12b20 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
12b30 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
12b40 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
12b50 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20  xRoundup..**.** 
12b60 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
12b70 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
12b80 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
12b90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
12ba0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
12bb0 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
12bc0 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
12bd0 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
12be0 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
12bf0 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
12c00 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
12c10 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
12c20 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
12c30 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
12c40 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
12c50 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
12c60 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
12c70 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
12c80 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
12c90 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
12ca0 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
12cb0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
12cc0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
12cd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
12ce0 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
12cf0 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
12d00 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
12d10 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
12d20 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
12d30 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
12d40 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
12d50 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
12d60 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
12d70 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
12d80 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12d90 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
12da0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
12db0 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
12dc0 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
12dd0 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
12de0 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
12df0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
12e00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
12e10 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
12e20 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
12e30 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
12e40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
12e50 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (For example,.*
12e60 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
12e70 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
12e80 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
12e90 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
12ea0 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
12eb0 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
12ec0 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
12ed0 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
12ee0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
12ef0 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
12f00 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
12f10 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
12f20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
12f30 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
12f40 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
12f50 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
12f60 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
12f70 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
12f80 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
12f90 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
12fa0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
12fb0 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
12fc0 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
12fd0 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
12fe0 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
12ff0 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
13000 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
13010 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
13020 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
13030 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
13040 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
13050 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
13060 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
13070 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
13080 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
13090 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
130a0 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
130b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
130c0 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
130d0 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
130e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
130f0 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
13100 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
13110 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
13120 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
13130 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
13140 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
13150 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
13160 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
13170 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
13180 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
13190 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
131a0 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
131b0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
131c0 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
131d0 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
131e0 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
131f0 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
13200 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
13210 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
13220 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
13230 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
13240 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
13250 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
13260 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
13270 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
13280 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
13290 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
132a0 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
132b0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
132c0 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
132d0 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
132e0 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
132f0 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
13300 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
13310 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
13320 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
13330 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
13340 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
13350 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
13360 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
13370 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
13380 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
13390 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
133a0 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
133b0 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
133c0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
133d0 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
133e0 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
133f0 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
13400 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
13410 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
13420 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
13430 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
13440 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
13450 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
13460 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
13470 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
13480 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
13490 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
134a0 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
134b0 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
134c0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
134d0 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
134e0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
134f0 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
13500 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
13510 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20  tion Options.** 
13520 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69  KEYWORDS: {confi
13530 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d  guration option}
13540 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
13550 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
13560 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
13570 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13580 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
13590 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
135a0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
135b0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
135c0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
135d0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
135e0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
135f0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
13600 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
13610 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
13620 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
13630 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13640 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
13650 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
13660 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
13670 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
13680 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
13690 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
136a0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
136b0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
136c0 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
136d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
136e0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
136f0 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
13700 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
13710 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
13720 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
13730 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
13740 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
13750 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
13760 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13770 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
13780 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13790 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
137a0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
137b0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
137c0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
137d0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
137e0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
137f0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
13800 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
13810 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
13820 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
13830 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
13840 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
13850 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
13860 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
13870 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
13880 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
13890 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
138a0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
138b0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
138c0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
138d0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
138e0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
138f0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
13900 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
13910 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
13920 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
13930 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
13940 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
13950 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
13960 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
13970 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
13980 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13990 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
139a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
139b0 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
139c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
139d0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
139e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
139f0 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74  ULTITHREAD]] <dt
13a00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13a10 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
13a20 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
13a30 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
13a40 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
13a50 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
13a60 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
13a70 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
13a80 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
13a90 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
13aa0 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
13ab0 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
13ac0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
13ad0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13ae0 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
13af0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
13b00 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
13b10 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
13b20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
13b30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13b40 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
13b50 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
13b60 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
13b70 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
13b80 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
13b90 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
13ba0 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
13bb0 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
13bc0 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
13bd0 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
13be0 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
13bf0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
13c00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13c10 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
13c20 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
13c30 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13c40 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13c50 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13c60 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13c70 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13c80 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
13c90 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
13ca0 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
13cb0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
13cc0 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
13cd0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13ce0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
13cf0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
13d00 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
13d10 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
13d20 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
13d30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13d40 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
13d50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13d60 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74  SERIALIZED]] <dt
13d70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
13d80 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
13d90 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
13da0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
13db0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
13dc0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
13dd0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
13de0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61  g mode] to Seria
13df0 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20  lized. In other 
13e00 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69  words, this opti
13e10 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c  on enables.** al
13e20 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64  l mutexes includ
13e30 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76  ing the recursiv
13e40 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20  e.** mutexes on 
13e50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13e60 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
13e70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
13e80 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68  bjects..** In th
13e90 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69  is mode (which i
13ea0 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68  s the default wh
13eb0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
13ec0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53  piled with.** [S
13ed0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13ee0 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20  =1]) the SQLite 
13ef0 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73  library will its
13f00 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63  elf serialize ac
13f10 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61  cess.** to [data
13f20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
13f30 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13f40 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74  statements] so t
13f50 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  hat the.** appli
13f60 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74  cation is free t
13f70 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b  o use the same [
13f80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13f90 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73  ion] or the.** s
13fa0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
13fb0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66  atement] in diff
13fc0 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74  erent threads at
13fd0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
13fe0 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  ** ^If SQLite is
13ff0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
14000 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
14010 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
14020 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
14030 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14040 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
14050 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
14060 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c  o set the Serial
14070 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
14080 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
14090 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
140a0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
140b0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
140c0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
140d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
140e0 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67  ERIALIZED config
140f0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
14100 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14110 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14120 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
14130 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
14140 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
14150 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14160 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14170 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
14180 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
14190 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
141a0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
141b0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
141c0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
141d0 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
141e0 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
141f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14200 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
14210 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
14220 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
14230 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
14240 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
14250 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d  ite.)^ ^SQLite m
14260 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20  akes.** its own 
14270 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
14280 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
14290 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
142a0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
142b0 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  re.** before the
142c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
142d0 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
142e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
142f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14300 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
14310 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
14320 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
14330 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
14340 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14350 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
14360 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14370 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
14380 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
14390 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
143a0 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
143b0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
143c0 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
143d0 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
143e0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
143f0 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
14400 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
14410 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
14420 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
14430 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
14440 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
14450 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
14460 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
14470 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
14480 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14490 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
144a0 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
144b0 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
144c0 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
144d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
144e0 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53  EMSTATUS]] <dt>S
144f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
14500 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
14510 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
14520 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
14530 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
14540 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
14550 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
14560 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
14570 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
14580 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
14590 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
145a0 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
145b0 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
145c0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
145d0 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
145e0 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  , the .** follow
145f0 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
14600 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
14610 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
14620 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
14630 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
14640 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
14650 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
14660 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
14670 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
14680 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
14690 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
146a0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
146b0 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  us()].**   </ul>
146c0 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
146d0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
146e0 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
146f0 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
14700 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
14710 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
14720 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
14730 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
14740 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
14750 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
14760 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
14770 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
14780 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
14790 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
147a0 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
147b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
147c0 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
147d0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
147e0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
147f0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
14800 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
14810 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63  se for.** scratc
14820 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65  h memory.  There
14830 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
14840 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72  ents:  A pointer
14850 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
14860 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
14870 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
14880 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
14890 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
148a0 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
148b0 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
148c0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
148d0 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
148e0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
148f0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
14900 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a  ons (N).  The sz
14910 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  .** argument mus
14920 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20  t be a multiple 
14930 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69  of 16..** The fi
14940 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
14950 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  t be a pointer t
14960 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  o an 8-byte alig
14970 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66  ned buffer.** of
14980 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
14990 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
149a0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
149b0 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e  use no more than
149c0 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66   two scratch buf
149d0 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e  fers per thread.
149e0 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64    So.** N should
149f0 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65   be set to twice
14a00 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61   the expected ma
14a10 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
14a20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c  threads..** ^SQL
14a30 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
14a40 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68  equire a scratch
14a50 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
14a60 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
14a70 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
14a80 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66  e page size. ^If
14a90 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
14aa0 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
14ab0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
14ac0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
14ad0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
14ae0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14af0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
14b00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14b10 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
14b20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
14b30 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64  mory needed.</dd
14b40 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14b50 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14b60 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
14b70 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
14b80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14b90 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
14ba0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
14bb0 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
14bc0 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
14bd0 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
14be0 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
14bf0 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
14c00 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
14c10 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
14c20 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
14c30 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
14c40 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
14c50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
14c60 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
14c70 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
14c80 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  aded using the S
14c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14ca0 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  CHE option..** T
14cb0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
14cc0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
14cd0 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
14ce0 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69  er to 8-byte ali
14cf0 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
14d00 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
14d10 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
14d20 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
14d30 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
14d40 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
14d50 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
14d60 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
14d70 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
14d80 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
14d90 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
14da0 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75  2 and 32768) plu
14db0 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61  s a little extra
14dc0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
14dd0 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
14de0 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65  page header size
14df0 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74   is 20 to 40 byt
14e00 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a  es depending on.
14e10 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68  ** the host arch
14e20 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69  itecture.  ^It i
14e30 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
14e40 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
14e50 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20  d memory,.** to 
14e60 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65  make sz a little
14e70 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65   too large.  The
14e80 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
14e90 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
14ea0 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
14eb0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
14ec0 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
14ed0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
14ee0 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
14ef0 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
14f00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14f10 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
14f20 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
14f30 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
14f40 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
14f50 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
14f60 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
14f70 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
14f80 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
14f90 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
14fa0 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
14fb0 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
14fc0 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
14fd0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
14fe0 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
14ff0 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
15000 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  ** The pointer i
15010 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
15020 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
15030 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
15040 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
15050 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
15060 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
15070 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
15080 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
15090 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
150a0 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
150b0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
150c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
150d0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
150e0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
150f0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
15100 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
15110 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
15120 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
15130 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
15140 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
15150 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
15160 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
15170 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
15180 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15190 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
151a0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
151b0 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
151c0 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
151d0 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
151e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
151f0 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
15200 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
15210 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
15220 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
15230 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
15240 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
15250 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
15260 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
15270 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
15280 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
15290 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
152a0 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
152b0 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
152c0 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
152d0 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
152e0 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
152f0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
15300 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
15310 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
15320 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68  ot NULL and eith
15330 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
15340 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a  E_MEMSYS3] or.**
15350 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
15360 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66  MEMSYS5] are def
15370 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61  ined, then the a
15380 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
15390 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
153a0 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
153b0 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
153c0 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
153d0 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
153e0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
153f0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
15400 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
15410 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
15420 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
15430 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
15440 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
15450 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
15460 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
15470 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
15480 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
15490 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
154a0 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
154b0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
154c0 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
154d0 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
154e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
154f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15500 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
15510 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
15520 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
15530 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15540 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
15550 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
15560 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
15570 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
15580 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15590 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
155a0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
155b0 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
155c0 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
155d0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
155e0 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
155f0 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
15600 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
15610 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
15620 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
15630 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
15640 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
15650 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
15660 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
15670 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
15680 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
15690 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
156a0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
156b0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
156c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
156d0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
156e0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
156f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15700 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
15710 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
15720 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
15730 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
15740 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
15750 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
15760 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
15770 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
15780 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
15790 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
157a0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
157b0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
157c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
157d0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
157e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
157f0 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
15800 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
15810 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15820 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
15830 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
15840 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
15850 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
15860 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15870 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
15880 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
15890 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
158a0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
158b0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
158c0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
158d0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
158e0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
158f0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
15900 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
15910 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
15920 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
15930 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
15940 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
15950 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
15960 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
15970 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
15980 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
15990 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
159a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
159b0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
159c0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
159d0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
159e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
159f0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
15a00 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
15a10 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
15a20 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
15a30 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
15a40 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
15a50 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
15a60 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
15a70 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
15a80 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15a90 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
15aa0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
15ab0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15ac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
15ad0 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
15ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
15af0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
15b00 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
15b10 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
15b20 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
15b30 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
15b40 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
15b50 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
15b60 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
15b70 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
15b80 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
15b90 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
15ba0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
15bb0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
15bc0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
15bd0 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
15be0 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
15bf0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
15c00 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
15c10 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
15c20 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
15c30 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
15c40 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
15c50 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
15c60 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
15c70 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15c80 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
15c90 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15ca0 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
15cb0 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
15cc0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
15cd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
15ce0 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
15cf0 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
15d00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15d10 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 3c 64  NFIG_PCACHE]] <d
15d20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15d30 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
15d40 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
15d50 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15d60 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15d70 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
15d80 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ** an [sqlite3_p
15d90 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f  cache_methods] o
15da0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
15db0 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68  ect specifies th
15dc0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  e interface.** t
15dd0 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
15de0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
15df0 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65  tion.)^  ^SQLite
15e00 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
15e10 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
15e20 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
15e30 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
15e40 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
15e50 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15e60 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15e70 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
15e80 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15e90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
15ea0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
15eb0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15ec0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
15ed0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
15ee0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
15ef0 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
15f00 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
15f10 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
15f20 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  * page cache imp
15f30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
15f40 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
15f50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
15f70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15f80 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
15f90 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
15fa0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
15fb0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
15fc0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
15fd0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
15fe0 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
15ff0 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
16000 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
16010 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
16020 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
16030 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
16040 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
16050 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
16060 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
16070 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
16080 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
16090 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
160a0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
160b0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
160c0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
160d0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
160e0 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
160f0 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
16100 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
16110 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
16120 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
16130 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
16140 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
16150 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
16160 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
16170 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
16180 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
16190 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
161a0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
161b0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
161c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
161d0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
161e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
161f0 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
16200 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16210 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
16220 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
16230 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
16240 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
16250 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
16260 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
16270 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
16280 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
16290 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
162a0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
162b0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
162c0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
162d0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
162e0 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
162f0 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
16300 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
16310 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
16320 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
16330 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
16340 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
16350 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
16360 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
16370 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
16380 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
16390 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
163a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
163b0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
163c0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
163d0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
163e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
163f0 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
16400 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
16410 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  dd> This option 
16420 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16430 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
16440 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  int. If non-zero
16450 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61  , then.** URI ha
16460 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16470 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
16480 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
16490 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68  zero, then URI h
164a0 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c  andling.** is gl
164b0 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
164c0 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67   If URI handling
164d0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
164e0 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
164f0 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f  mes.** passed to
16500 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
16510 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
16520 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
16530 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
16540 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
16550 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
16560 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
16570 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
16580 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
16590 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
165a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
165b0 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
165c0 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
165d0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
165e0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66  on is opened. If
165f0 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20   it is globally 
16600 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61  disabled, filena
16610 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20  mes are.** only 
16620 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
16630 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54  RIs if the SQLIT
16640 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20  E_OPEN_URI flag 
16650 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a  is set when the.
16660 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
16670 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
16680 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  . By default, UR
16690 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
166a0 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
166b0 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
166c0 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
166d0 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
166e0 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
166f0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
16700 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
16710 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
16720 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16730 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
16740 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
16750 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16760 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
16770 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
16780 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16790 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
167a0 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
167b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
167c0 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
167d0 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
167e0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
167f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16800 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
16810 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
16820 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
16830 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16840 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
16850 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
16860 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
16870 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16880 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
16890 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
168a0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
168b0 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
168c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
168d0 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
168e0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
168f0 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
16900 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16910 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
16920 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
16930 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16940 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
16950 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
16960 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16970 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16990 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
169a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
169b0 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
169c0 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
169d0 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
169e0 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
169f0 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
16a00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16a10 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
16a20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
16a30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16a40 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
16a50 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69       14  /* sqli
16a60 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
16a70 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16a90 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
16aa0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
16ab0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
16ac0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16ad0 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
16ae0 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
16af0 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
16b00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
16b10 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
16b20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  int */../*.** CA
16b30 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
16b40 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66   Connection Conf
16b50 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
16b60 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
16b70 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
16b80 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
16b90 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
16ba0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
16bb0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
16bc0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
16bd0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
16be0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
16bf0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
16c00 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
16c10 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
16c20 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
16c30 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
16c40 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
16c50 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
16c60 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
16c70 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
16c80 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
16c90 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
16ca0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
16cb0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
16cc0 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
16cd0 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
16ce0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
16cf0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64   ^The [sqlite3_d
16d00 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
16d10 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
16d20 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
16d30 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
16d40 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
16d50 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
16d60 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16d70 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
16d80 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
16d90 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
16da0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
16db0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
16dc0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68   option takes th
16dd0 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  ree additional a
16de0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
16df0 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20  termine the .** 
16e00 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
16e10 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
16e20 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74  figuration for t
16e30 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
16e40 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68  nection]..** ^Th
16e50 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16e60 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
16e70 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
16e80 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
16e90 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
16ea0 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
16eb0 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
16ec0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a  kaside memory..*
16ed0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
16ee0 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20  ument after the 
16ef0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16f00 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a  LOOKASIDE verb.*
16f10 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  * may be NULL in
16f20 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
16f30 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
16f40 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64   the.** lookasid
16f50 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  e buffer itself 
16f60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
16f70 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73  alloc()]. ^The s
16f80 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
16f90 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
16fa0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
16fb0 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54  buffer slot.  ^T
16fc0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
16fd0 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
16fe0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
16ff0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
17000 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
17010 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
17020 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
17030 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
17040 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
17050 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
17060 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  rd arguments.  T
17070 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73  he buffer.** mus
17080 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
17090 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
170a0 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63  ry.  ^If the sec
170b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
170c0 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ** SQLITE_DBCONF
170d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20  IG_LOOKASIDE is 
170e0 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f  not a multiple o
170f0 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72  f 8, it is inter
17100 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64  nally.** rounded
17110 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78   down to the nex
17120 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70  t smaller multip
17130 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20  le of 8.  ^(The 
17140 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
17150 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
17160 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65  n for a database
17170 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20   connection can 
17180 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20  only be changed 
17190 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e  when that.** con
171a0 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63  nection is not c
171b0 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c  urrently using l
171c0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c  ookaside memory,
171d0 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72   or in other wor
171e0 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22  ds.** when the "
171f0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72  current value" r
17200 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
17210 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73  qlite3_db_status
17220 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ](D,[SQLITE_CONF
17230 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e  IG_LOOKASIDE],..
17240 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41  .) is zero..** A
17250 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68  ny attempt to ch
17260 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
17270 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67  de memory config
17280 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f  uration when loo
17290 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79  kaside.** memory
172a0 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65   is in use leave
172b0 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  s the configurat
172c0 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e  ion unchanged an
172d0 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  d returns .** [S
172e0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f  QLITE_BUSY].)^</
172f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
17300 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
17310 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a  ABLE_FKEY</dt>.*
17320 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17330 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
17340 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
17350 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74   the enforcement
17360 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   of.** [foreign 
17370 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
17380 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  .  There should 
17390 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
173a0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
173b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
173c0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
173d0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
173e0 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  isable FK enforc
173f0 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69  ement,.** positi
17400 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20  ve to enable FK 
17410 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e  enforcement or n
17420 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
17430 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a   FK enforcement.
17440 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  ** unchanged.  T
17450 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17460 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
17470 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
17480 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
17490 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
174a0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
174b0 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  er FK enforcemen
174c0 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a  t is off or on.*
174d0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
174e0 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
174f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
17500 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
17510 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
17520 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f  case the FK enfo
17530 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20  rcement setting 
17540 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
17550 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
17560 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
17570 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
17580 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  GGER</dt>.** <dd
17590 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
175a0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
175b0 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45   or disable [CRE
175c0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
175d0 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72  iggers]..** Ther
175e0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
175f0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
17600 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
17610 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
17620 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
17630 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
17640 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73  triggers,.** pos
17650 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
17660 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61  triggers or nega
17670 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
17680 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
17690 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
176a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
176b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
176c0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
176d0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
176e0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
176f0 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67  ate whether trig
17700 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65  gers are disable
17710 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
17720 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
17730 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
17740 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
17750 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
17760 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
17770 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73  se the trigger s
17780 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
17790 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
177a0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
177b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
177c0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
177d0 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20  IDE       1001  
177e0 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
177f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17800 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
17810 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32  LE_FKEY     1002
17820 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
17830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17840 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17850 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f  TRIGGER  1003  /
17860 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a  * int int* */...
17870 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17880 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
17890 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
178a0 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  t Codes.**.** ^T
178b0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
178c0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
178d0 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
178e0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
178f0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
17900 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
17910 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
17920 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
17930 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
17940 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
17950 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
17960 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
17970 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ity..*/.SQLITE_A
17980 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
17990 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
179a0 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
179b0 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
179c0 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
179d0 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
179e0 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
179f0 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
17a00 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
17a10 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
17a20 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
17a30 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
17a40 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
17a50 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
17a60 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
17a70 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
17a80 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
17a90 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
17aa0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
17ab0 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
17ac0 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
17ad0 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
17ae0 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
17af0 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
17b00 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
17b10 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
17b20 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
17b30 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
17b40 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
17b50 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
17b60 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
17b70 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
17b80 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73  owid] of the mos
17b90 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
17ba0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
17bb0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
17bc0 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
17bd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17be0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
17bf0 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20   argument.  ^As 
17c00 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
17c10 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f  n 3.7.7, this ro
17c20 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64  utines.** record
17c30 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
17c40 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20  t rowid of both 
17c50 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20  ordinary tables 
17c60 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62  and [virtual tab
17c70 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  les]..** ^If no 
17c80 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
17c90 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
17ca0 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
17cb0 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
17cc0 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
17cd0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
17ce0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
17cf0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
17d00 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
17d10 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
17d20 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
17d30 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
17d40 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
17d50 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
17d60 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
17d70 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
17d80 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
17d90 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
17da0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
17db0 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
17dc0 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
17dd0 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
17de0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
17df0 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
17e00 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
17e10 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
17e20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
17e30 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
17e40 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
17e50 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
17e60 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
17e70 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
17e80 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
17e90 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
17ea0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
17eb0 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
17ec0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
17ed0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
17ee0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
17ef0 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
17f00 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
17f10 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
17f20 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
17f30 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
17f40 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
17f50 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
17f60 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
17f70 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
17f80 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
17f90 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
17fa0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
17fb0 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
17fc0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
17fd0 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
17fe0 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
17ff0 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
18000 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
18010 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
18020 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
18030 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
18040 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
18050 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
18060 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
18070 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
18080 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
18090 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
180a0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
180b0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
180c0 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
180d0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
180e0 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
180f0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
18100 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
18110 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
18120 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
18130 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
18140 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
18150 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
18160 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
18170 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
18180 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
18190 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
181a0 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
181b0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
181c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
181d0 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [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 0a 2a 2a 20 66 75 6e 63  rowid()].** func
18200 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
18210 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
18220 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
18230 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
18240 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
18250 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
18260 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
18270 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
18280 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
18290 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
182a0 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
182b0 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
182c0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
182d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
182e0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
182f0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18300 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
18310 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18320 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
18330 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
18340 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
18350 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
18360 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
18370 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
18380 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
18390 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
183a0 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
183b0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
183c0 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
183d0 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
183e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
183f0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
18400 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
18410 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
18420 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
18430 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
18440 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
18450 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
18460 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
18470 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
18480 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
18490 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
184a0 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
184b0 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
184c0 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
184d0 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
184e0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
184f0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
18500 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
18510 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
18520 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
18530 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
18540 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
18550 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
18560 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
18570 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
18580 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
18590 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
185a0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
185b0 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
185c0 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
185d0 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
185e0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
185f0 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
18600 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
18610 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
18620 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
18630 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
18640 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
18650 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
18660 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
18670 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
18680 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
18690 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
186a0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
186b0 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
186c0 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
186d0 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
186e0 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
186f0 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
18700 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
18710 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
18720 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
18730 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
18740 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
18750 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
18760 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
18770 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
18780 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
18790 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
187a0 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
187b0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
187c0 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
187d0 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
187e0 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
187f0 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
18800 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
18810 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
18820 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
18830 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
18840 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
18850 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
18860 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
18870 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
18880 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
18890 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
188a0 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
188b0 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
188c0 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
188d0 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
188e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
188f0 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
18900 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
18910 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
18920 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
18930 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
18940 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
18950 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
18960 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
18970 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
18980 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
18990 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
189a0 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
189b0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
189c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
189d0 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
189e0 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
189f0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
18a00 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
18a10 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
18a20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
18a30 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
18a40 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
18a50 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
18a60 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
18a70 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
18a80 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
18a90 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
18aa0 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
18ab0 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
18ac0 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
18ad0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
18ae0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
18af0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
18b00 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
18b10 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
18b20 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
18b30 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
18b40 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
18b50 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
18b60 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
18b70 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
18b80 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
18b90 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
18ba0 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
18bb0 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
18bc0 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
18bd0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
18be0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
18bf0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
18c00 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
18c10 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
18c20 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
18c30 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
18c40 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
18c50 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
18c60 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
18c70 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
18c80 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
18c90 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
18ca0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
18cb0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
18cc0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
18cd0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
18ce0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
18cf0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
18d00 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
18d10 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
18d20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18d30 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
18d40 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
18d50 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
18d60 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
18d70 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
18d80 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
18d90 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
18da0 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
18db0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
18dc0 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
18dd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
18de0 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
18df0 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
18e00 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
18e10 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
18e20 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
18e30 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
18e40 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
18e50 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
18e60 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
18e70 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
18e80 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
18e90 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
18ea0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
18eb0 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
18ec0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
18ed0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
18ee0 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
18ef0 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
18f00 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
18f10 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
18f20 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
18f30 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
18f40 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
18f50 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
18f60 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
18f70 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
18f80 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
18f90 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
18fa0 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
18fb0 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
18fc0 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
18fd0 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
18fe0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
18ff0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
19000 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
19010 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
19020 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
19030 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
19040 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
19050 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
19060 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
19070 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
19080 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
19090 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
190a0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
190b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
190c0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
190d0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
190e0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
190f0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
19100 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
19110 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
19120 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
19130 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
19140 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
19150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19160 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
19170 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
19180 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
19190 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
191a0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
191b0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
191c0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
191d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
191e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
191f0 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
19200 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
19210 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
19220 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
19230 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  uery.**.** ^This
19240 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
19250 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
19260 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
19270 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
19280 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
19290 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
192a0 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
192b0 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
192c0 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
192d0 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
192e0 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
192f0 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
19300 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
19310 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
19320 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
19330 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
19340 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
19350 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
19360 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
19370 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
19380 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
19390 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
193a0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
193b0 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
193c0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
193d0 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
193e0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
193f0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
19400 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
19410 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
19420 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
19430 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
19440 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
19450 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
19460 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
19470 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
19480 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
19490 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
194a0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
194b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
194c0 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
194d0 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
194e0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
194f0 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
19500 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
19510 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
19520 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
19530 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
19540 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
19550 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
19560 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
19570 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
19580 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
19590 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
195a0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
195b0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
195c0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
195d0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
195e0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
195f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
19600 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
19610 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
19620 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
19630 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19640 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
19650 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
19660 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
19670 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
19680 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
19690 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
196a0 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
196b0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
196c0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
196d0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
196e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
196f0 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
19700 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
19710 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
19720 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
19730 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
19740 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
19750 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
19760 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
19770 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
19780 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
19790 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
197a0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
197b0 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
197c0 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
197d0 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
197e0 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
197f0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
19800 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
19810 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
19820 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
19830 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
19840 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
19850 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
19860 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
19870 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
19880 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
19890 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
198a0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
198b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
198c0 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
198d0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
198e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
198f0 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
19900 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
19910 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
19920 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
19930 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
19940 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49   happen..*/.SQLI
19950 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
19960 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
19970 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19980 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
19990 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
199a0 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
199b0 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
199c0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
199d0 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
199e0 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
199f0 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
19a00 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
19a10 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
19a20 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
19a30 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
19a40 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
19a50 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
19a60 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
19a70 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
19a80 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
19a90 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
19aa0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
19ab0 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
19ac0 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
19ad0 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
19ae0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
19af0 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
19b00 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
19b10 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
19b20 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
19b30 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
19b40 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
19b50 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
19b60 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
19b70 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
19b80 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
19b90 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
19ba0 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
19bb0 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
19bc0 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
19bd0 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
19be0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
19bf0 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
19c00 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
19c10 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
19c20 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
19c30 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
19c40 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
19c50 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
19c60 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
19c70 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
19c80 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
19c90 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
19ca0 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
19cb0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
19cc0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
19cd0 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
19ce0 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
19cf0 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
19d00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
19d10 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
19d20 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
19d30 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
19d40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
19d50 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
19d60 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
19d70 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
19d80 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
19d90 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
19da0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
19db0 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
19dc0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
19dd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
19de0 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
19df0 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
19e00 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19e10 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
19e20 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
19e30 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
19e40 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
19e50 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19e60 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
19e70 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
19e80 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
19e90 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
19ea0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19eb0 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
19ec0 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
19ed0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
19ee0 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
19ef0 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
19f00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
19f10 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
19f20 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
19f30 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
19f40 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
19f50 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
19f60 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
19f70 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
19f80 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
19f90 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
19fa0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
19fb0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
19fc0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
19fd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
19fe0 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
19ff0 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  *sql);.SQLITE_AP
1a000 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
1a010 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
1a020 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
1a030 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
1a040 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
1a050 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
1a060 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a  _BUSY Errors.**.
1a070 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1a080 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
1a090 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d   function that m
1a0a0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1a0b0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
1a0c0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1a0d0 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73  o open a databas
1a0e0 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f  e table that ano
1a0f0 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
1a100 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
1a110 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  cked..**.** ^If 
1a120 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1a130 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
1a140 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
1a150 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
1a160 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65  LOCKED].** is re
1a170 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1a180 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
1a190 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
1a1a0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1a1b0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
1a1c0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
1a1d0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
1a1e0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
1a1f0 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
1a200 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1a210 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
1a220 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
1a230 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1a240 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
1a250 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
1a260 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1a270 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1a280 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
1a290 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1a2a0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1a2b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1a2c0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
1a2d0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
1a2e0 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
1a2f0 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
1a300 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
1a310 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
1a320 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
1a330 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
1a340 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
1a350 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
1a360 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
1a370 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
1a380 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
1a390 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
1a3a0 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  D] is returned..
1a3b0 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
1a3c0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1a3d0 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
1a3e0 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
1a3f0 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
1a400 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
1a410 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
1a420 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1a430 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1a440 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1a450 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1a460 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1a470 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1a480 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1a490 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1a4a0 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1a4b0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1a4c0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1a4d0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1a4e0 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1a4f0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1a500 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1a510 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1a520 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
1a530 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65  R_BLOCKED] inste
1a540 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
1a550 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1a560 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
1a570 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
1a580 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
1a590 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
1a5a0 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
1a5b0 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
1a5c0 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
1a5d0 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
1a5e0 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
1a5f0 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
1a600 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
1a610 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
1a620 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
1a630 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
1a640 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1a650 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
1a660 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
1a670 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
1a680 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
1a690 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
1a6a0 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
1a6b0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1a6c0 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
1a6d0 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
1a6e0 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
1a6f0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1a700 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
1a710 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
1a720 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
1a730 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
1a740 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
1a750 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
1a760 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
1a770 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
1a780 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
1a790 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
1a7a0 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
1a7b0 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
1a7c0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
1a7d0 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
1a7e0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1a7f0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1a800 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
1a810 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
1a820 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
1a830 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
1a840 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
1a850 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
1a860 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
1a870 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
1a880 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
1a890 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
1a8a0 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
1a8b0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
1a8c0 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
1a8d0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
1a8e0 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
1a8f0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
1a900 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
1a910 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
1a920 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
1a930 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
1a940 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
1a950 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
1a960 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
1a970 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
1a980 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
1a990 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20  * readers.  ^If 
1a9a0 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
1a9b0 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
1a9c0 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
1a9d0 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
1a9e0 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
1a9f0 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
1aa00 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
1aa10 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
1aa20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
1aa30 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
1aa40 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
1aa50 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
1aa60 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
1aa70 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
1aa80 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64   ^This error cod
1aa90 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66  e promotion.** f
1aaa0 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74  orces an automat
1aab0 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74  ic rollback of t
1aac0 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65  he changes.  See
1aad0 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
1aae0 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70  "/cvstrac/wiki?p
1aaf0 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f  =CorruptionFollo
1ab00 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a  wingBusyError">.
1ab10 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ** CorruptionFol
1ab20 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c  lowingBusyError<
1ab30 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f  /a> wiki page fo
1ab40 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f  r a discussion o
1ab50 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73  f why.** this is
1ab60 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a   important..**.*
1ab70 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1ab80 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1ab90 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
1aba0 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
1abb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1abc0 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
1abd0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
1abe0 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
1abf0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1ac00 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
1ac10 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
1ac20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1ac30 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20  eout()].** will 
1ac40 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
1ac50 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  r the busy handl
1ac60 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1ac70 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1ac80 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1ac90 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1aca0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1acb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1acc0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1acd0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1ace0 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
1acf0 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
1ad00 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
1ad10 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
1ad20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1ad30 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
1ad40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1ad50 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
1ad60 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1ad70 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1ad80 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49  handler..*/.SQLI
1ad90 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1ada0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1adb0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
1adc0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
1add0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1ade0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
1adf0 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e   Timeout.**.** ^
1ae00 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1ae10 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
1ae20 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
1ae30 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
1ae40 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
1ae50 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
1ae60 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
1ae70 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
1ae80 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
1ae90 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
1aea0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
1aeb0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1aec0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1aed0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
1aee0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
1aef0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
1af00 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1af10 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
1af20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
1af30 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
1af40 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
1af50 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
1af60 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
1af70 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
1af80 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
1af90 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
1afa0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
1afb0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
1afc0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
1afd0 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
1afe0 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
1aff0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1b000 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1b010 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1b020 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
1b030 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1b040 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
1b050 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
1b060 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
1b070 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
1b080 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
1b090 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1b0a0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
1b0b0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
1b0c0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
1b0d0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
1b0e0 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
1b0f0 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
1b100 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  I int sqlite3_bu
1b110 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
1b120 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
1b130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1b140 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
1b150 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
1b160 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Queries.**.** Th
1b170 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1b180 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1b190 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1b1a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1b1b0 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1b1c0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1b1d0 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1b1e0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1b1f0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1b200 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1b210 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1b220 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1b230 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1b240 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1b250 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1b260 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1b270 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1b280 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1b290 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1b2a0 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1b2b0 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1b2c0 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1b2d0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1b2e0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1b2f0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1b300 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1b310 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1b320 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1b330 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1b340 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1b350 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1b360 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1b370 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1b380 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1b390 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1b3a0 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1b3b0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1b3c0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1b3d0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1b3e0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1b3f0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1b400 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1b410 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1b420 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1b430 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1b440 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1b450 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1b460 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1b470 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1b480 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1b490 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1b4a0 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1b4b0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1b4c0 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1b4d0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1b4e0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1b4f0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1b500 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1b510 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1b520 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1b530 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1b540 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1b550 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1b560 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1b570 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1b580 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1b590 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1b5a0 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1b5b0 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1b5c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1b5d0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1b5e0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1b5f0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1b600 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1b610 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1b620 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1b630 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1b640 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1b650 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1b660 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1b670 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b680 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1b690 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1b6a0 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1b6b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b6c0 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1b6d0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1b6e0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1b6f0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1b700 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1b710 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1b720 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b730 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1b740 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1b750 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1b760 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1b770 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1b780 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1b790 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1b7a0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1b7b0 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1b7c0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1b7d0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1b7e0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1b7f0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1b800 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b810 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b820 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1b830 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b840 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1b850 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1b860 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1b870 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1b880 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b890 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1b8a0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1b8b0 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1b8c0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b8d0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1b8e0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1b8f0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1b900 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1b910 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1b920 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1b930 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1b940 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1b950 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1b960 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1b970 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1b980 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1b990 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1b9a0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1b9b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1b9c0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1b9d0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1b9e0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1b9f0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1ba00 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1ba10 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1ba20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1ba30 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1ba40 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1ba50 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1ba60 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1ba70 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1ba80 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1ba90 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1baa0 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1bab0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1bac0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1bad0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1bae0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1baf0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1bb00 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1bb10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1bb20 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1bb30 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1bb40 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1bb50 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1bb60 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1bb70 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1bb80 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1bb90 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1bba0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1bbb0 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1bbc0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1bbd0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1bbe0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1bbf0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1bc00 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1bc10 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1bc20 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1bc30 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1bc40 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1bc50 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1bc60 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1bc70 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1bc80 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1bc90 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1bca0 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1bcb0 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1bcc0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1bcd0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1bce0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1bcf0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1bd00 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1bd10 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1bd20 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1bd30 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1bd40 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1bd50 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1bd60 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1bd70 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1bd80 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1bd90 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1bda0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1bdb0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1bdc0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1bdd0 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
1bde0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
1bdf0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1be00 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
1be10 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
1be20 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
1be30 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
1be40 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
1be50 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
1be60 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
1be70 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1be80 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
1be90 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
1bea0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
1beb0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1bec0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
1bed0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
1bee0 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
1bef0 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
1bf00 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1bf10 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .);.SQLITE_API v
1bf20 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1bf30 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1bf40 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1bf50 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1bf60 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1bf70 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1bf80 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1bf90 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1bfa0 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1bfb0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1bfc0 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1bfd0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1bfe0 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
1bff0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1c000 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1c010 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1c020 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1c030 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1c040 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1c050 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1c060 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1c070 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1c080 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1c090 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1c0a0 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1c0b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1c0c0 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1c0d0 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1c0e0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1c0f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1c100 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1c110 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1c120 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1c130 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1c140 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1c150 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1c160 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1c170 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1c180 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1c190 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1c1a0 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1c1b0 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1c1c0 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1c1d0 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1c1e0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1c1f0 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1c200 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1c210 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1c220 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1c230 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1c240 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1c250 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1c260 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1c270 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1c280 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1c290 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1c2a0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1c2b0 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1c2c0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1c2d0 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1c2e0 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1c2f0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1c300 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1c310 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1c320 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1c330 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1c340 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1c350 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1c360 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1c370 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1c380 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1c390 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1c3a0 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1c3b0 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1c3c0 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1c3d0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1c3e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1c3f0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1c400 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1c410 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1c420 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1c430 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1c440 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1c450 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1c460 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1c470 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1c480 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1c490 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1c4a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1c4b0 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1c4c0 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1c4d0 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1c4e0 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1c4f0 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1c500 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1c510 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1c520 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1c530 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1c540 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1c550 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1c560 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1c570 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1c580 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1c590 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1c5a0 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1c5b0 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1c5c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1c5d0 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1c5e0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1c5f0 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1c600 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1c610 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1c620 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1c630 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1c640 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1c650 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1c660 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1c670 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1c680 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1c690 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
1c6a0 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1c6b0 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1c6c0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1c6d0 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1c6e0 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d  utes a null-term
1c6f0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1c700 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
1c710 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
1c720 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
1c730 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
1c740 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
1c750 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
1c760 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
1c770 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
1c780 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
1c790 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
1c7a0 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
1c7b0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
1c7c0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
1c7d0 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
1c7e0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
1c7f0 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
1c800 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
1c810 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
1c820 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
1c830 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c840 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c850 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
1c860 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
1c870 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
1c880 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1c890 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
1c8a0 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
1c8b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
1c8c0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1c8d0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c8e0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1c8f0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1c900 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1c910 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
1c920 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1c930 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1c940 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1c950 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1c960 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1c970 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1c980 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
1c990 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
1c9a0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
1c9b0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
1c9c0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
1c9d0 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
1c9e0 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
1c9f0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1ca00 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1ca10 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1ca20 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1ca30 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
1ca40 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
1ca50 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1ca60 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
1ca70 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
1ca80 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
1ca90 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
1caa0 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
1cab0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
1cac0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
1cad0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1cae0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1caf0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
1cb00 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
1cb10 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1cb20 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1cb30 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
1cb40 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
1cb50 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
1cb60 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
1cb70 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
1cb80 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
1cb90 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
1cba0 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
1cbb0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1cbc0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
1cbd0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1cbe0 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
1cbf0 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
1cc00 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
1cc10 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
1cc20 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
1cc30 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
1cc40 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
1cc50 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
1cc60 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
1cc70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
1cc80 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
1cc90 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
1cca0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
1ccb0 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
1ccc0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
1ccd0 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
1cce0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1ccf0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1cd00 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1cd10 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1cd20 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
1cd30 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
1cd40 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1cd50 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1cd60 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1cd70 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1cd80 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1cd90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
1cda0 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
1cdb0 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
1cdc0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1cdd0 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
1cde0 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
1cdf0 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
1ce00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1ce10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
1ce20 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1ce30 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
1ce40 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
1ce50 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
1ce60 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
1ce70 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
1ce80 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
1ce90 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
1cea0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1ceb0 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
1cec0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
1ced0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
1cee0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
1cef0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1cf00 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,...);.SQLITE_AP
1cf10 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1cf20 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
1cf30 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1cf40 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1cf50 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
1cf60 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1cf70 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53  t char*, ...);.S
1cf80 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1cf90 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1cfa0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1cfb0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1cfc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cfd0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1cfe0 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
1cff0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
1d000 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
1d010 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
1d020 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
1d030 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
1d040 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d050 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
1d060 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
1d070 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
1d080 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
1d090 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
1d0a0 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
1d0b0 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
1d0c0 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
1d0d0 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
1d0e0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
1d0f0 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
1d100 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1d110 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1d120 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1d130 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
1d140 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
1d150 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1d160 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
1d170 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
1d180 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
1d190 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1d1a0 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
1d1b0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
1d1c0 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
1d1d0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1d1e0 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
1d1f0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
1d200 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1d210 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
1d220 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
1d230 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1d240 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
1d250 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1d260 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
1d270 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
1d280 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
1d290 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
1d2a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d2b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1d2c0 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
1d2d0 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
1d2e0 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
1d2f0 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
1d300 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1d310 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
1d320 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
1d330 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1d340 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
1d350 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1d360 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
1d370 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
1d380 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
1d390 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
1d3a0 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
1d3b0 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
1d3c0 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
1d3d0 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
1d3e0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
1d3f0 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
1d400 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1d410 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
1d420 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
1d430 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
1d440 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1d450 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
1d460 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
1d470 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
1d480 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1d490 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
1d4a0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
1d4b0 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
1d4c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1d4d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1d4e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d4f0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ()..**.** ^(The 
1d500 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d510 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
1d520 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
1d530 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
1d540 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
1d550 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1d560 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
1d570 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1d580 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
1d590 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1d5a0 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
1d5b0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
1d5c0 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74  ameter.)^ ^ If t
1d5d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1d5e0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1d5f0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
1d600 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1d610 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1d620 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1d630 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1d640 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
1d650 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
1d660 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1d670 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d680 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63  ..** ^If the sec
1d690 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1d6a0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d6b0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
1d6c0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1d6d0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1d6e0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1d6f0 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1d700 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
1d710 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
1d720 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1d730 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d740 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1d750 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
1d760 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1d770 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d780 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
1d790 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1d7a0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
1d7b0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1d7c0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
1d7d0 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
1d7e0 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
1d7f0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
1d800 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
1d810 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
1d820 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
1d830 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
1d840 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
1d850 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
1d860 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
1d870 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
1d880 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1d890 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1d8a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1d8b0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
1d8c0 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
1d8d0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
1d8e0 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1d8f0 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1d900 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1d910 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
1d920 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1d930 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1d940 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1d950 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1d960 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1d970 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1d980 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1d990 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1d9a0 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1d9b0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1d9c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1d9d0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1d9e0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1d9f0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1da00 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1da10 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1da20 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1da30 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1da40 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1da50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1da60 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1da70 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1da80 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1da90 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1daa0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1dab0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1dac0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1dad0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
1dae0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1daf0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1db00 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
1db10 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1db20 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1db30 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1db40 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1db50 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1db60 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1db70 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1db80 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1db90 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1dba0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1dbb0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1dbc0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1dbd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1dbe0 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
1dbf0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
1dc00 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
1dc10 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
1dc20 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
1dc30 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
1dc40 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
1dc50 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
1dc60 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
1dc70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1dc80 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1dc90 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1dca0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
1dcb0 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
1dcc0 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
1dcd0 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
1dce0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1dcf0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
1dd00 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1dd10 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
1dd20 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
1dd30 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
1dd40 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1dd50 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
1dd60 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
1dd70 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
1dd80 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
1dd90 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
1dda0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1ddb0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
1ddc0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1ddd0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1dde0 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
1ddf0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51  _malloc(int);.SQ
1de00 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
1de10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
1de20 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  oid*, int);.SQLI
1de30 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
1de40 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
1de50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1de60 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1de70 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
1de80 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
1de90 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
1dea0 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
1deb0 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
1dec0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
1ded0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1dee0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
1def0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1df00 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1df10 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
1df20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
1df30 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1df40 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
1df50 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
1df60 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1df70 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1df80 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1df90 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
1dfa0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
1dfb0 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
1dfc0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
1dfd0 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
1dfe0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1dff0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
1e000 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
1e010 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
1e020 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1e030 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
1e040 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1e050 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
1e060 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
1e070 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1e080 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1e090 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1e0a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1e0b0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
1e0c0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
1e0d0 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
1e0e0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
1e0f0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
1e100 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
1e110 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
1e120 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
1e130 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
1e140 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
1e150 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
1e160 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e170 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
1e180 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
1e190 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
1e1a0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
1e1b0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
1e1c0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1e1d0 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
1e1e0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
1e1f0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
1e200 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1e210 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
1e220 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
1e230 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
1e240 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1e250 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
1e260 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1e270 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
1e280 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c  he reset..*/.SQL
1e290 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1e2a0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1e2b0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
1e2c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
1e2d0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1e2e0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1e2f0 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
1e300 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e310 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
1e320 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
1e330 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
1e340 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
1e350 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
1e360 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
1e370 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
1e380 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
1e390 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
1e3a0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
1e3b0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
1e3c0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
1e3d0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
1e3e0 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
1e3f0 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
1e400 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
1e410 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
1e420 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
1e430 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
1e440 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
1e450 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
1e460 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
1e470 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
1e480 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
1e490 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
1e4a0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
1e4b0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
1e4c0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
1e4d0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
1e4e0 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
1e4f0 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66   P..**.** ^The f
1e500 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72  irst time this r
1e510 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65  outine is invoke
1e520 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e  d (either intern
1e530 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68  ally or by.** th
1e540 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74  e application) t
1e550 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
1e560 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1e570 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ss obtained.** f
1e580 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
1e590 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
1e5a0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1e5b0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1e5c0 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65  ** ^On all subse
1e5d0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
1e5e0 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
1e5f0 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
1e600 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
1e610 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
1e620 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
1e630 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
1e640 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
1e650 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  hod..*/.SQLITE_A
1e660 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1e670 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
1e680 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
1e690 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1e6a0 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
1e6b0 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
1e6c0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
1e6d0 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
1e6e0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
1e6f0 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
1e700 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1e710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e720 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
1e730 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1e740 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
1e750 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1e760 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
1e770 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
1e780 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
1e790 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
1e7a0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1e7b0 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
1e7c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
1e7d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1e7e0 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
1e7f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1e800 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
1e810 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
1e820 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
1e830 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
1e840 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
1e850 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
1e860 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
1e870 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
1e880 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e890 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
1e8a0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
1e8b0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
1e8c0 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
1e8d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
1e8e0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
1e8f0 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
1e900 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
1e910 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1e920 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
1e930 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
1e940 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
1e950 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1e960 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
1e970 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
1e980 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
1e990 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
1e9a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1e9b0 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
1e9c0 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
1e9d0 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
1e9e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1e9f0 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
1ea00 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1ea10 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
1ea20 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
1ea30 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
1ea40 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
1ea50 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1ea60 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1ea70 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1ea80 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
1ea90 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1eaa0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1eab0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
1eac0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1ead0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
1eae0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
1eaf0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
1eb00 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
1eb10 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
1eb20 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1eb30 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
1eb40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1eb50 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1eb60 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1eb70 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
1eb80 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1eb90 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1eba0 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
1ebb0 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
1ebc0 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
1ebd0 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
1ebe0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1ebf0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1ec00 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
1ec10 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
1ec20 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
1ec30 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
1ec40 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
1ec50 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
1ec60 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
1ec70 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1ec80 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
1ec90 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
1eca0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
1ecb0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
1ecc0 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
1ecd0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1ece0 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
1ecf0 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
1ed00 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
1ed10 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
1ed20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1ed30 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
1ed40 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
1ed50 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
1ed60 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
1ed70 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
1ed80 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1ed90 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1eda0 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
1edb0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1edc0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
1edd0 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
1ede0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1edf0 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
1ee00 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
1ee10 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
1ee20 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
1ee30 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
1ee40 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
1ee50 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
1ee60 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
1ee70 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
1ee80 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
1ee90 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
1eea0 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
1eeb0 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
1eec0 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
1eed0 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
1eee0 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
1eef0 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
1ef00 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1ef10 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
1ef20 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
1ef30 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
1ef40 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1ef50 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
1ef60 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
1ef70 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
1ef80 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
1ef90 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
1efa0 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
1efb0 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
1efc0 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
1efd0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
1efe0 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
1eff0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1f000 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
1f010 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
1f020 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
1f030 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
1f040 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
1f050 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
1f060 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
1f070 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
1f080 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
1f090 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
1f0a0 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
1f0b0 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
1f0c0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
1f0d0 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
1f0e0 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
1f0f0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
1f100 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
1f110 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
1f120 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
1f130 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
1f140 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
1f150 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
1f160 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1f170 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
1f180 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
1f190 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
1f1a0 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
1f1b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
1f1c0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
1f1d0 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
1f1e0 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
1f1f0 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
1f200 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
1f210 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f220 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
1f230 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
1f240 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
1f250 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1f260 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
1f270 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
1f280 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
1f290 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
1f2a0 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
1f2b0 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
1f2c0 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
1f2d0 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
1f2e0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1f2f0 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
1f300 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
1f310 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
1f320 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1f330 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
1f340 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
1f350 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
1f360 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
1f370 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
1f380 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
1f390 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f3a0 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
1f3b0 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
1f3c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1f3d0 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
1f3e0 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
1f3f0 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
1f400 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
1f410 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
1f420 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
1f430 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1f440 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
1f450 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
1f460 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1f470 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1f480 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1f490 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1f4a0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1f4b0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1f4c0 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
1f4d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
1f4e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1f4f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f500 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1f510 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1f520 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1f530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f540 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1f550 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1f560 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1f570 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
1f580 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f590 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
1f5a0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1f5b0 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
1f5c0 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
1f5d0 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
1f5e0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1f5f0 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
1f600 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
1f610 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
1f620 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
1f630 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1f640 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
1f650 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
1f660 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
1f670 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
1f680 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
1f690 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
1f6a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1f6b0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
1f6c0 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
1f6d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1f6e0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1f6f0 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
1f700 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
1f710 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
1f720 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
1f730 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
1f740 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
1f750 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
1f760 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
1f770 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
1f780 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
1f790 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f7a0 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
1f7b0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
1f7c0 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
1f7d0 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  nge..*/.SQLITE_A
1f7e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
1f7f0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1f800 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1f810 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1f820 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1f830 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1f840 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1f850 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1f860 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1f870 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1f880 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1f890 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1f8a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1f8b0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1f8c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1f8d0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
1f8e0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
1f8f0 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
1f900 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
1f910 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
1f920 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
1f930 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
1f940 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
1f950 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
1f960 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1f970 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1f980 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
1f990 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
1f9a0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1f9b0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1f9c0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
1f9d0 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
1f9e0 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54  used as a [SQLIT
1f9f0 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74  E_ROLLBACK | ret
1fa00 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f  urn code].** fro
1fa10 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
1fa20 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
1fa30 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
1fa40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fa50 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
1fa60 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
1fa70 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
1fa80 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
1fa90 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
1faa0 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
1fab0 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
1fac0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
1fad0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
1fae0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1faf0 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
1fb00 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1fb10 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1fb20 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
1fb30 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
1fb40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
1fb50 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
1fb60 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
1fb70 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
1fb80 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
1fb90 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1fba0 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
1fbb0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1fbc0 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
1fbd0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
1fbe0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
1fbf0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
1fc00 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
1fc10 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
1fc20 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
1fc30 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1fc40 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
1fc50 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
1fc60 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
1fc70 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
1fc80 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
1fc90 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
1fca0 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
1fcb0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
1fcc0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
1fcd0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
1fce0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
1fcf0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
1fd00 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
1fd10 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
1fd20 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
1fd30 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1fd40 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
1fd50 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
1fd60 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
1fd70 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1fd80 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1fd90 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
1fda0 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
1fdb0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
1fdc0 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
1fdd0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1fde0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fdf0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
1fe00 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
1fe10 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1fe20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1fe30 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1fe40 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1fe50 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1fe60 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1fe70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1fe80 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
1fe90 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
1fea0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1feb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fec0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
1fed0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
1fee0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
1fef0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ff00 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
1ff10 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
1ff20 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1ff30 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ff40 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ff50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1ff60 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
1ff70 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1ff80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ff90 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ffa0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
1ffb0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1ffc0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1ffd0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ffe0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1fff0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
20000 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20010 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20020 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20030 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
20040 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
20050 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
20060 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20070 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20080 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
20090 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
200a0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
200b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
200c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
200d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
200e0 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
200f0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
20100 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
20110 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20120 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
20130 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
20140 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
20150 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20160 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20170 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
20180 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
20190 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
201a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
201b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
201c0 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
201d0 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
201e0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
201f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20200 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20210 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
20220 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
20230 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20240 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20250 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20260 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
20270 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
20280 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
20290 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
202a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
202b0 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
202c0 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
202d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
202e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
202f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20300 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
20310 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
20320 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
20330 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20340 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20350 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
20360 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
20370 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
20380 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20390 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
203a0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
203b0 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
203c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
203d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
203e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
203f0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
20400 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
20410 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
20420 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20430 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
20440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
20450 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
20460 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
20470 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20480 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
20490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
204a0 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
204b0 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
204c0 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
204d0 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
204e0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
204f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20500 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
20510 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20520 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
20530 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
20540 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
20550 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20560 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20570 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
20580 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
20590 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
205a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
205b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
205c0 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
205d0 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
205e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
205f0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
20600 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20610 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
20620 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
20630 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
20640 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20650 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20660 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
20670 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
20680 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
20690 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
206a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
206b0 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
206c0 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
206d0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
206e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
206f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20700 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
20710 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
20720 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
20730 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20750 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
20760 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
20770 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
20780 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20790 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
207a0 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
207b0 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
207c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
207d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
207e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
207f0 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
20800 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
20810 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
20820 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
20830 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
20840 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
20850 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
20860 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
20870 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
20880 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
20890 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
208a0 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
208b0 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
208c0 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
208d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
208e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
208f0 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
20900 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
20910 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
20920 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
20930 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
20940 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
20950 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
20960 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
20970 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
20980 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
20990 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
209a0 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
209b0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
209c0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
209d0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
209e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
209f0 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
20a00 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
20a10 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
20a20 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
20a30 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
20a40 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
20a50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
20a60 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
20a70 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
20a80 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
20a90 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
20aa0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
20ab0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
20ac0 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
20ad0 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
20ae0 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
20af0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
20b00 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
20b10 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
20b20 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
20b30 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
20b40 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
20b50 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
20b60 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
20b70 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
20b80 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
20b90 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ^.**.** ^The cal
20ba0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
20bb0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
20bc0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
20bd0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
20be0 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
20bf0 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
20c00 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
20c10 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
20c20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
20c30 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
20c40 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
20c50 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
20c60 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
20c70 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
20c80 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
20c90 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
20ca0 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
20cb0 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
20cc0 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
20cd0 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
20ce0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
20cf0 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
20d00 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
20d10 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
20d20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
20d30 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
20d40 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
20d50 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
20d60 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
20d70 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
20d80 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
20d90 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
20da0 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
20db0 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
20dc0 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
20dd0 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
20de0 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
20df0 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
20e00 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
20e10 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20e20 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
20e30 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
20e40 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
20e50 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
20e60 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
20e70 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
20e80 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
20e90 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
20ea0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
20eb0 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
20ec0 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
20ed0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
20ee0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
20ef0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
20f00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
20f10 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
20f20 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
20f30 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
20f40 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
20f50 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
20f60 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
20f70 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
20f80 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
20f90 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
20fa0 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
20fb0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
20fc0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
20fd0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
20fe0 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
20ff0 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
21000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21010 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
21020 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
21030 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
21040 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
21050 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
21060 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
21070 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
21080 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
21090 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
210a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
210b0 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
210c0 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
210d0 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
210e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  he number of .**
210f0 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
21100 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
21110 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
21120 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
21130 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
21140 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
21150 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  back X..**.** ^O
21160 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
21170 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
21180 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
21190 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
211a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
211b0 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
211c0 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
211d0 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
211e0 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
211f0 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
21200 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
21210 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
21220 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
21230 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
21240 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
21250 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
21260 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
21270 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
21280 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
21290 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
212a0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
212b0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
212c0 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
212d0 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
212e0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
212f0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
21300 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
21310 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
21320 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
21330 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
21340 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
21350 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
21360 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
21370 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
21380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
21390 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
213a0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
213b0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
213c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
213d0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
213e0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
213f0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
21400 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21410 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
21420 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
21430 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
21440 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45  ph..**.*/.SQLITE
21450 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
21460 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
21470 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
21480 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
21490 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
214a0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
214b0 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
214c0 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
214d0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
214e0 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
214f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
21500 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
21510 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
21520 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
21530 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
21540 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
21550 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
21560 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
21570 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
21580 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
21590 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
215a0 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
215b0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
215c0 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
215d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
215e0 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
215f0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
21600 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
21610 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
21620 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
21630 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
21640 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
21650 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
21660 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
21670 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
21680 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
21690 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
216a0 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
216b0 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
216c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
216d0 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
216e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
216f0 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
21700 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
21710 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
21720 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
21730 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
21740 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
21750 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
21760 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
21770 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
21780 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
21790 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
217a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
217b0 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
217c0 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
217d0 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
217e0 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
217f0 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
21800 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
21810 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
21820 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
21830 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
21840 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
21850 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
21860 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
21870 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
21880 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
21890 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
218a0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
218b0 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
218c0 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
218d0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
218e0 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
218f0 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
21900 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
21910 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
21920 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
21930 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21940 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
21950 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
21960 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
21970 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
21980 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
21990 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
219a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
219b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
219c0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
219d0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
219e0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
219f0 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
21a00 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
21a10 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
21a20 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
21a30 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
21a40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21a50 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
21a60 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
21a70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21a80 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
21a90 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
21aa0 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
21ab0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
21ac0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
21ad0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
21ae0 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
21af0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
21b00 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
21b10 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
21b20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
21b30 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
21b40 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
21b50 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
21b60 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
21b70 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
21b80 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
21b90 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
21ba0 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
21bb0 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
21bc0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
21bd0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
21be0 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
21bf0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
21c00 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
21c10 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
21c20 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
21c30 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
21c40 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
21c50 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
21c60 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
21c70 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
21c80 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
21c90 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
21ca0 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
21cb0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
21cc0 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
21cd0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
21ce0 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
21cf0 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
21d00 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
21d10 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
21d20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
21d30 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
21d40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
21d50 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
21d60 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
21d70 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
21d80 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
21d90 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
21da0 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
21db0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
21dc0 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
21dd0 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
21de0 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
21df0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21e00 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
21e10 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
21e20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
21e30 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
21e40 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21e50 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
21e60 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
21e70 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
21e80 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
21e90 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
21ea0 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
21eb0 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
21ec0 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
21ed0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
21ee0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
21ef0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
21f00 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
21f10 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
21f20 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
21f30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21f40 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
21f50 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
21f60 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
21f70 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
21f80 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
21f90 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
21fa0 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
21fb0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
21fc0 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
21fd0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
21fe0 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
21ff0 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
22000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22010 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
22020 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
22030 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
22040 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
22050 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
22060 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
22070 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
22080 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
22090 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
220a0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
220b0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
220c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
220d0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
220e0 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
220f0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
22100 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
22110 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
22120 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
22130 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
22140 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
22150 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
22160 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
22170 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
22180 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
22190 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
221a0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
221b0 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
221c0 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
221d0 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
221e0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
221f0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
22200 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
22210 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
22220 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
22230 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
22240 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
22250 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
22260 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
22270 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
22280 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
22290 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
222a0 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
222b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
222c0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
222d0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
222e0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
222f0 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
22300 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
22310 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
22320 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
22330 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
22340 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
22350 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
22360 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
22370 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
22380 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
22390 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
223a0 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
223b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
223c0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
223d0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
223e0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
223f0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
22400 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
22410 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
22420 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
22430 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
22440 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
22450 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
22460 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
22470 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
22480 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
22490 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
224a0 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
224b0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
224c0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
224d0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
224e0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
224f0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
22500 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
22510 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
22520 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
22530 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
22540 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
22550 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
22560 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
22570 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
22580 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
22590 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
225a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
225b0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
225c0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
225d0 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
225e0 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
225f0 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
22600 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
22610 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
22620 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
22630 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
22640 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
22650 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
22660 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
22670 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
22680 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
22690 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
226a0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
226b0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
226c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
226d0 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
226e0 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61   in the fourth a
226f0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
22700 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
22710 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
22720 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
22730 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
22740 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
22750 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
22760 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
22770 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
22780 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
22790 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
227a0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
227b0 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76  * As of SQLite v
227c0 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52  ersion 3.7.7, UR
227d0 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
227e0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
227f0 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
22800 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
22810 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
22820 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
22830 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
22840 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
22850 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
22860 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
22870 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
22880 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
22890 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
228a0 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
228b0 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
228c0 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
228d0 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
228e0 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
228f0 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
22900 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
22910 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
22920 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
22930 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
22940 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
22950 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
22960 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
22970 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
22980 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
22990 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
229a0 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
229b0 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
229c0 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
229d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
229e0 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
229f0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
22a00 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
22a10 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
22a20 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
22a30 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
22a40 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
22a50 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
22a60 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
22a70 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
22a80 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
22a90 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
22aa0 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
22ab0 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
22ac0 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
22ad0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
22ae0 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
22af0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
22b00 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
22b10 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
22b20 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
22b30 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20  e path. .** ^On 
22b40 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
22b50 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
22b60 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
22b70 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
22b80 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
22b90 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a  .g. "C:")..**.**
22ba0 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
22bb0 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
22bc0 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
22bd0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
22be0 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
22bf0 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
22c00 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
22c10 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
22c20 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
22c30 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
22c40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
22c50 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  ..** SQLite inte
22c60 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f  rprets the follo
22c70 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 79  wing three query
22c80 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
22c90 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
22ca0 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
22cb0 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
22cc0 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
22cd0 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
22ce0 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
22cf0 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
22d00 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
22d10 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
22d20 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
22d30 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
22d40 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
22d50 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
22d60 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
22d70 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
22d80 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
22d90 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
22da0 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
22db0 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
22dc0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
22dd0 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
22de0 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
22df0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
22e00 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
22e10 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
22e20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
22e30 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
22e40 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
22e50 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
22e60 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
22e70 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
22e80 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
22e90 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
22ea0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
22eb0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
22ec0 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
22ed0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
22ee0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
22ef0 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a  "ro", "rw" or.**
22f00 20 20 20 20 20 22 72 77 63 22 2e 20 41 74 74 65       "rwc". Atte
22f10 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
22f20 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
22f30 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f 72 29  lue is an error)
22f40 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
22f50 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
22f60 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
22f70 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
22f80 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
22f90 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
22fa0 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
22fb0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
22fc0 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
22fd0 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
22fe0 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
22ff0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65  t to sqlite3_pre
23000 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74  pare_v2(). ^If t
23010 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
23020 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
23030 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
23040 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
23050 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
23060 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
23070 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
23080 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
23090 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
230a0 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
230b0 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
230c0 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
230d0 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
230e0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
230f0 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
23100 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
23110 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
23120 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
23130 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  E. ^If sqlite3_o
23140 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20  pen_v2() is .** 
23150 20 20 20 20 75 73 65 64 2c 20 69 74 20 69 73 20      used, it is 
23160 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
23170 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 20  ify a value for 
23180 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
23190 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a 20 20  er that is .**  
231a0 20 20 20 6c 65 73 73 20 72 65 73 74 72 69 63 74     less restrict
231b0 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
231c0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
231d0 6c 61 67 73 20 70 61 73 73 65 64 20 61 73 20 74  lags passed as t
231e0 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20 20 20  he third .**    
231f0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
23200 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
23210 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
23220 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
23230 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
23240 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
23250 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
23260 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
23270 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
23280 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
23290 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
232a0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
232b0 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
232c0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
232d0 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
232e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
232f0 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
23300 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
23310 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
23320 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
23330 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
23340 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
23350 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
23360 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
23370 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
23380 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
23390 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
233a0 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
233b0 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
233c0 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
233d0 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
233e0 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62 79  our requested by
233f0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
23400 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
23410 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
23420 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
23430 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75  CHE flag..** </u
23440 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
23450 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
23460 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
23470 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
23480 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
23490 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
234a0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
234b0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
234c0 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
234d0 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
234e0 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
234f0 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
23500 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
23510 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
23520 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
23530 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
23540 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
23550 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
23560 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
23570 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
23580 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
23590 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
235a0 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
235b0 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
235c0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
235d0 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
235e0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
235f0 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
23600 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
23610 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
23620 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
23630 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
23640 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
23650 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
23660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
23670 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
23680 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
23690 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
236a0 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
236b0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
236c0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
236d0 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
236e0 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
236f0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
23700 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
23710 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
23720 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
23730 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23740 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
23750 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
23760 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
23770 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
23780 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
23790 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
237a0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
237b0 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
237c0 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
237d0 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
237e0 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
237f0 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
23800 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
23810 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
23820 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
23830 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
23840 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
23850 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
23860 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
23870 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
23880 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
23890 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
238a0 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
238b0 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
238c0 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
238d0 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
238e0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
238f0 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
23900 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
23910 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
23920 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
23930 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
23940 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
23950 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
23960 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
23970 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
23980 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
23990 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
239a0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
239b0 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
239c0 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
239d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
239e0 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
239f0 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c  .db?vfs=unix-nol
23a00 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ock <td>.**     
23a10 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
23a20 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23a30 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
23a40 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e  cial VFS "unix-n
23a50 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  olock"..** <tr><
23a60 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
23a70 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
23a80 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
23a90 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
23aa0 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
23ab0 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
23ac0 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
23ad0 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
23ae0 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
23af0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
23b00 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
23b10 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
23b20 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
23b30 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
23b40 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
23b50 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
23b60 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
23b70 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
23b80 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
23b90 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
23ba0 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
23bb0 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
23bc0 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
23bd0 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
23be0 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
23bf0 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
23c00 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
23c10 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
23c20 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
23c30 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
23c40 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
23c50 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
23c60 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
23c70 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
23c80 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
23c90 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
23ca0 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
23cb0 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
23cc0 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
23cd0 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
23ce0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
23cf0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
23d00 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
23d10 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
23d20 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
23d30 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
23d40 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
23d50 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
23d60 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
23d70 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
23d80 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
23d90 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
23da0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
23db0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
23dc0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
23dd0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
23de0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
23df0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
23e00 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
23e10 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
23e20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
23e30 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
23e40 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a  3_open_v2()..*/.
23e50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
23e60 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
23e70 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
23e80 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
23e90 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
23ea0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
23eb0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
23ec0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
23ed0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
23ee0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
23ef0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
23f00 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
23f10 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
23f20 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
23f30 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
23f40 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
23f50 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
23f60 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
23f70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
23f80 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
23f90 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
23fa0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
23fb0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
23fc0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
23fd0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
23fe0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
23ff0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
24000 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
24010 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
24020 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
24030 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
24040 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
24050 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
24060 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
24070 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
24080 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
24090 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
240a0 69 73 20 69 73 20 61 20 75 74 69 6c 69 74 79 20  is is a utility 
240b0 72 6f 75 74 69 6e 65 2c 20 75 73 65 66 75 6c 20  routine, useful 
240c0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
240d0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
240e0 63 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  cks.** to see if
240f0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
24100 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
24110 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
24120 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
24130 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
24140 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
24150 76 61 6c 75 65 20 6f 66 20 74 68 65 20 71 75 65  value of the que
24160 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
24170 0a 2a 2a 20 54 68 65 20 7a 46 69 6c 65 6e 61 6d  .** The zFilenam
24180 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  e argument is th
24190 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
241a0 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
241b0 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 6d 65  he xOpen().** me
241c0 74 68 6f 64 20 6f 66 20 61 20 56 46 53 20 69 6d  thod of a VFS im
241d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
241e0 68 65 20 7a 50 61 72 61 6d 20 61 72 67 75 6d 65  he zParam argume
241f0 6e 74 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  nt is the name o
24200 66 20 74 68 65 0a 2a 2a 20 71 75 65 72 79 20 70  f the.** query p
24210 61 72 61 6d 65 74 65 72 20 77 65 20 73 65 65 6b  arameter we seek
24220 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
24230 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
24240 65 20 6f 66 20 74 68 65 20 7a 50 61 72 61 6d 0a  e of the zParam.
24250 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
24260 69 74 20 65 78 69 73 74 73 2e 20 20 49 66 20 74  it exists.  If t
24270 68 65 20 70 61 72 61 6d 65 74 65 72 20 64 6f 65  he parameter doe
24280 73 20 6e 6f 74 20 65 78 69 73 74 2c 20 74 68 69  s not exist, thi
24290 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74  s routine.** ret
242a0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
242b0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
242c0 65 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72 67 75  e zFilename argu
242d0 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e  ment to this fun
242e0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 20 70  ction is not a p
242f0 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
24300 74 65 0a 2a 2a 20 70 61 73 73 65 64 20 69 6e 74  te.** passed int
24310 6f 20 74 68 65 20 78 4f 70 65 6e 20 56 46 53 20  o the xOpen VFS 
24320 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
24330 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
24340 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20  s routine.** is 
24350 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
24360 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
24370 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  le..*/.SQLITE_AP
24380 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
24390 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
243a0 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
243b0 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
243c0 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
243d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
243e0 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
243f0 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
24400 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
24410 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
24420 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
24430 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
24440 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
24450 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
24460 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
24470 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
24480 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
24490 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
244a0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
244b0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
244c0 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
244d0 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
244e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
244f0 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
24500 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
24510 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
24520 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
24530 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
24540 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
24550 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
24560 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
24570 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
24580 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
24590 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
245a0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
245b0 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
245c0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
245d0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
245e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
245f0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
24600 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
24610 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
24620 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
24630 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
24640 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
24650 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
24660 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
24670 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
24680 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
24690 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
246a0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
246b0 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
246c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
246d0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
246e0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
246f0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
24700 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
24710 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
24720 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
24730 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
24740 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
24750 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
24760 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
24770 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
24780 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
24790 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
247a0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
247b0 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
247c0 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
247d0 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
247e0 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
247f0 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
24800 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
24810 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
24820 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
24830 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
24840 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
24850 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
24860 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
24870 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
24880 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
24890 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
248a0 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
248b0 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
248c0 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
248d0 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
248e0 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
248f0 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
24900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24910 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
24920 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
24930 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
24940 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
24950 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
24960 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
24970 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
24980 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
24990 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
249a0 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
249b0 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
249c0 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
249d0 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
249e0 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
249f0 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
24a00 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
24a10 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
24a20 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
24a30 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
24a40 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
24a50 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
24a60 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
24a70 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
24a80 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
24a90 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
24aa0 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   set..*/.SQLITE_
24ab0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
24ac0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
24ad0 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
24ae0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
24af0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
24b00 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
24b10 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
24b20 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
24b30 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  g(sqlite3*);.SQL
24b40 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
24b50 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
24b60 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
24b70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24b80 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
24b90 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
24ba0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
24bb0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
24bc0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
24bd0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
24be0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
24bf0 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
24c00 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
24c10 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
24c20 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
24c30 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
24c40 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
24c50 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
24c60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
24c70 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
24c80 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
24c90 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
24ca0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
24cb0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
24cc0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
24cd0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
24ce0 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
24cf0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
24d00 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
24d10 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
24d20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
24d30 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
24d40 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
24d50 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
24d60 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
24d70 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
24d80 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
24d90 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
24da0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
24db0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
24dc0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
24dd0 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
24de0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
24df0 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
24e00 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
24e10 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
24e20 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
24e30 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
24e40 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
24e50 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
24e60 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
24e70 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
24e80 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
24e90 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
24ea0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
24eb0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
24ec0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
24ed0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
24ee0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
24ef0 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
24f00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
24f10 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
24f20 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
24f30 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
24f40 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
24f50 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
24f60 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
24f70 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
24f80 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
24f90 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
24fa0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
24fb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24fc0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
24fd0 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
24fe0 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
24ff0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
25000 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
25010 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
25020 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
25030 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
25040 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
25050 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
25060 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
25070 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
25080 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
25090 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
250a0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
250b0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
250c0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
250d0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
250e0 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
250f0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
25100 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
25110 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
25120 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
25130 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
25140 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
25150 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
25160 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
25170 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
25180 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
25190 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
251a0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
251b0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
251c0 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
251d0 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
251e0 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
251f0 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
25200 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
25210 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
25220 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
25230 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
25240 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
25250 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
25260 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
25270 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
25280 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
25290 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
252a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
252b0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
252c0 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
252d0 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
252e0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
252f0 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
25300 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
25310 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
25320 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
25330 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
25340 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
25350 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
25360 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
25370 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
25380 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
25390 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
253a0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
253b0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
253c0 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
253d0 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
253e0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
253f0 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
25400 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
25410 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
25420 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
25430 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
25440 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
25450 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
25460 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
25470 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
25480 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
25490 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
254a0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
254b0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
254c0 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
254d0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
254e0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
254f0 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
25500 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
25510 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
25520 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
25530 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
25540 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
25550 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
25560 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
25570 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
25580 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
25590 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
255a0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
255b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
255c0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
255d0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
255e0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
255f0 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
25600 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
25610 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
25620 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
25630 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
25640 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
25650 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
25660 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
25670 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
25680 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
25690 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
256a0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
256b0 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eases..*/.SQLITE
256c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
256d0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
256e0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
256f0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
25700 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
25710 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
25720 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
25730 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
25740 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
25750 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
25760 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
25770 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
25780 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
25790 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
257a0 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
257b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
257c0 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
257d0 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
257e0 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
257f0 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
25800 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
25810 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
25820 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
25830 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
25840 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
25850 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
25860 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25870 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
25880 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
25890 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
258a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
258b0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
258c0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
258d0 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
258e0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
258f0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
25900 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
25910 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
25920 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
25930 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
25940 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
25950 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
25960 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
25970 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
25980 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
25990 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
259a0 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
259b0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
259c0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
259d0 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
259e0 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
259f0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
25a00 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
25a10 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
25a20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
25a30 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
25a40 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
25a50 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
25a60 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
25a70 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
25a80 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
25a90 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
25aa0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
25ab0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
25ac0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
25ad0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
25ae0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
25af0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25b00 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
25b10 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
25b20 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
25b30 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
25b40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25b50 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
25b60 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
25b70 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
25b80 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25b90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
25ba0 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
25bb0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
25bc0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
25bd0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
25be0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
25bf0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
25c00 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
25c10 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
25c20 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
25c30 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
25c40 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
25c50 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
25c60 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
25c70 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
25c80 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
25c90 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
25ca0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25cb0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
25cc0 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
25cd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
25ce0 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
25cf0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25d00 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
25d10 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
25d20 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
25d30 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25d40 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
25d50 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
25d60 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
25d70 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25d80 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
25d90 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
25da0 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
25db0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25dc0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
25dd0 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
25de0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25df0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
25e00 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
25e10 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
25e20 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
25e30 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
25e40 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
25e50 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
25e60 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25e70 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
25e80 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
25e90 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
25ea0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
25eb0 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
25ec0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
25ed0 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
25ee0 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
25ef0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
25f00 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
25f10 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
25f20 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
25f30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
25f40 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
25f50 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25f60 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
25f70 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
25f80 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
25f90 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
25fa0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
25fb0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
25fc0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
25fd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
25fe0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
25ff0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
26000 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
26010 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
26020 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
26030 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
26040 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
26050 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
26060 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26070 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
26080 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
26090 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
260a0 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
260b0 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
260c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
260d0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
260e0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
260f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26100 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
26110 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
26120 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26130 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
26140 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
26150 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26160 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
26170 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
26180 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26190 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
261a0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
261b0 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
261c0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
261d0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
261e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
261f0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
26200 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
26210 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
26220 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
26230 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
26240 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
26250 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
26260 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
26270 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
26280 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
26290 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
262a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
262b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
262c0 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
262d0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
262e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
262f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26300 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
26310 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
26320 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
26330 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
26340 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
26350 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
26360 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
26370 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
26380 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
26390 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
263a0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
263b0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
263c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
263d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
263e0 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
263f0 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
26400 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
26410 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
26420 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26430 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
26440 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
26450 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
26460 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
26470 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
26480 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
26490 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
264a0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
264b0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
264c0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
264d0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
264e0 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
264f0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
26500 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
26510 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
26520 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
26530 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
26540 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
26550 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
26560 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
26570 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
26580 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
26590 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
265a0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
265b0 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
265c0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
265d0 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
265e0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
265f0 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
26600 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
26610 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
26620 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
26630 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
26640 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
26650 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
26660 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
26670 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
26680 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
26690 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61  rminator bytes a
266a0 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c  s this saves SQL
266b0 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20  ite from having 
266c0 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70  to.** make a cop
266d0 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73  y of the input s
266e0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tring..**.** ^If
266f0 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
26700 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
26710 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
26720 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
26730 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
26740 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
26750 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
26760 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
26770 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
26780 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
26790 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
267a0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
267b0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
267c0 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
267d0 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
267e0 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
267f0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
26800 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
26810 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26820 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
26830 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
26840 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
26850 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
26860 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
26870 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
26880 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
26890 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
268a0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
268b0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
268c0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
268d0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
268e0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
268f0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
26900 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
26910 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
26920 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
26930 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
26940 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
26950 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
26960 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
26970 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
26980 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
26990 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
269a0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
269b0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
269c0 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
269d0 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
269e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
269f0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
26a00 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
26a10 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
26a20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
26a30 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
26a40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
26a50 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
26a60 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
26a70 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
26a80 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
26a90 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
26aa0 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
26ab0 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
26ac0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
26ad0 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
26ae0 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
26af0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
26b00 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
26b10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
26b20 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
26b30 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
26b40 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
26b50 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
26b60 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
26b70 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
26b80 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
26b90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
26ba0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
26bb0 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
26bc0 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
26bd0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
26be0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
26bf0 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
26c00 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
26c10 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
26c20 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
26c30 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
26c40 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
26c50 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
26c60 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
26c70 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
26c80 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
26c90 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
26ca0 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  in..** </li>.**.
26cb0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
26cc0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
26cd0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
26ce0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
26cf0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
26d00 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
26d10 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
26d20 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
26d30 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
26d40 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
26d50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
26d60 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
26d70 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
26d80 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
26d90 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
26da0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
26db0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
26dc0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
26dd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
26de0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
26df0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
26e00 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
26e10 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
26e20 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
26e30 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
26e40 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
26e50 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
26e60 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
26e70 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
26e80 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
26e90 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
26ea0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
26eb0 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
26ec0 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
26ed0 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
26ee0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
26ef0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
26f00 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
26f10 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
26f20 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
26f30 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
26f40 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
26f50 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
26f60 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
26f70 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
26f80 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
26f90 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
26fa0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
26fb0 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
26fc0 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
26fd0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
26fe0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
26ff0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
27000 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
27010 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
27020 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
27030 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
27040 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
27050 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
27060 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
27070 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
27080 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
27090 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
270a0 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
270b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
270c0 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
270d0 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
270e0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
270f0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
27100 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
27110 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
27120 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e  ** the .** </li>
27130 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c  .** </ol>.*/.SQL
27140 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
27150 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
27160 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
27170 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
27180 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
27190 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
271a0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
271b0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
271c0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
271d0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
271e0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
271f0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
27200 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
27210 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
27220 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
27230 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
27240 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
27250 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
27260 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
27270 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
27280 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
27290 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
272a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
272b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
272c0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
272d0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
272e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
272f0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
27300 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
27310 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
27320 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
27330 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
27340 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
27350 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
27360 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
27370 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
27380 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
27390 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
273a0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
273b0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
273c0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
273d0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
273e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
273f0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
27400 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
27410 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
27420 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
27430 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
27440 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
27450 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
27460 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
27470 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
27480 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
27490 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
274a0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
274b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
274c0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
274d0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
274e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
274f0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
27500 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
27510 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
27520 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
27530 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
27540 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
27550 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
27560 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
27570 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
27580 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
27590 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
275a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
275b0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
275c0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
275d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
275e0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
275f0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
27600 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
27610 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
27620 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
27630 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
27640 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
27650 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
27660 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
27670 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
27680 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27690 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
276a0 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a  tement SQL.**.**
276b0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
276c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
276d0 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
276e0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
276f0 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
27700 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
27710 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27720 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
27730 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
27740 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
27750 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
27760 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
27770 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27780 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51  e16_v2()]..*/.SQ
27790 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
277a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
277b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
277c0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
277d0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
277e0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
277f0 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
27800 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20   Database.**.** 
27810 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
27820 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
27830 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27840 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
27850 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
27860 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
27870 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
27880 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
27890 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
278a0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
278b0 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
278c0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
278d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
278e0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
278f0 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
27900 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
27910 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
27920 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
27930 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
27940 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
27950 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
27960 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
27970 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
27980 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
27990 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
279a0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
279b0 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
279c0 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
279d0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
279e0 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
279f0 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
27a00 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
27a10 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
27a20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
27a30 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
27a40 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
27a50 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
27a60 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
27a70 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
27a80 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
27a90 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27aa0 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
27ab0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
27ac0 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
27ad0 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
27ae0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
27af0 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
27b00 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
27b10 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
27b20 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
27b30 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
27b40 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
27b50 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
27b60 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
27b70 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
27b80 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
27b90 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
27ba0 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
27bb0 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
27bc0 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
27bd0 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
27be0 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
27bf0 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
27c00 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
27c10 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
27c20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
27c30 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
27c40 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
27c50 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
27c60 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
27c70 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
27c80 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
27c90 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
27ca0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
27cb0 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
27cc0 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
27cd0 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
27ce0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
27cf0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
27d00 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
27d10 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  isk..*/.SQLITE_A
27d20 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
27d30 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
27d40 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
27d50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27d60 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
27d70 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
27d80 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
27d90 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
27da0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
27db0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27dc0 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
27dd0 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
27de0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
27df0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
27e00 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
27e10 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
27e20 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
27e30 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
27e40 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
27e50 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
27e60 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
27e70 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
27e80 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27e90 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
27ea0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
27eb0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
27ec0 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
27ed0 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
27ee0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
27ef0 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
27f00 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
27f10 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
27f20 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
27f30 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
27f40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27f50 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
27f60 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
27f70 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
27f80 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
27f90 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
27fa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
27fb0 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
27fc0 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
27fd0 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
27fe0 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
27ff0 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
28000 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
28010 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28020 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
28030 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
28040 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
28050 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
28060 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
28070 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
28080 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
28090 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
280a0 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
280b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
280c0 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
280d0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
280e0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
280f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28100 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
28110 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
28120 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
28130 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
28140 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
28150 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
28160 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
28170 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
28180 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
28190 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
281a0 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
281b0 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
281c0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
281d0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
281e0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
281f0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
28200 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
28210 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
28220 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
28230 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
28240 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
28250 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
28260 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
28270 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
28280 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
28290 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
282a0 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
282b0 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
282c0 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
282d0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
282e0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
282f0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
28300 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
28310 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
28320 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
28330 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
28340 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28350 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
28360 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
28370 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
28380 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
28390 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
283a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
283b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
283c0 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
283d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
283e0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
283f0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
28400 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
28410 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
28420 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
28430 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
28440 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
28450 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
28460 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
28470 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
28480 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
28490 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
284a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
284b0 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
284c0 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
284d0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
284e0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
284f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28500 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
28510 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
28520 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
28530 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28540 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
28550 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
28560 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
28570 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
28580 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
28590 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
285a0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
285b0 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
285c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
285d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
285e0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
285f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
28600 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
28610 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
28620 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
28630 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
28640 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
28650 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28660 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
28670 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
28680 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
28690 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
286a0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
286b0 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
286c0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
286d0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
286e0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
286f0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
28700 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
28710 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
28720 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
28730 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
28740 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
28750 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
28760 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
28770 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
28780 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
28790 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
287a0 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
287b0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
287c0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
287d0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
287e0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
287f0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
28800 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
28810 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
28820 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
28830 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
28840 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
28850 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
28860 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
28870 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28880 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
28890 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
288a0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
288b0 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
288c0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
288d0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
288e0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
288f0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
28900 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
28910 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
28920 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
28930 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
28940 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
28950 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
28960 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
28970 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
28980 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
28990 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
289a0 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
289b0 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
289c0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
289d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
289e0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
289f0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
28a00 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
28a10 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
28a20 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
28a30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
28a40 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
28a50 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
28a60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
28a70 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
28a80 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
28a90 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
28aa0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
28ab0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
28ac0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
28ad0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
28ae0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
28af0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
28b00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
28b10 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
28b20 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
28b30 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
28b40 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
28b50 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
28b60 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
28b70 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
28b80 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
28b90 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
28ba0 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
28bb0 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
28bc0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
28bd0 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
28be0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
28bf0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
28c00 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
28c10 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
28c20 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
28c30 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
28c40 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
28c50 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28c60 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
28c70 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
28c80 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
28c90 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
28ca0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
28cb0 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
28cc0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
28cd0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
28ce0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
28cf0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
28d00 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
28d10 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
28d20 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
28d30 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
28d40 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
28d50 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
28d60 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
28d70 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ameter..**.** ^(
28d80 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
28d90 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
28da0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
28db0 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
28dc0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
28dd0 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
28de0 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
28df0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
28e00 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
28e10 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
28e20 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
28e30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
28e40 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
28e50 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
28e60 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
28e70 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20  ive, the length 
28e80 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
28e90 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
28ea0 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
28eb0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
28ec0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 61  minator..** If a
28ed0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
28ee0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
28ef0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
28f00 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
28f10 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
28f20 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68  bind_text16() th
28f30 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  en that paramete
28f40 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
28f50 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
28f60 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
28f70 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
28f80 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
28f90 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
28fa0 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
28fb0 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
28fc0 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
28fd0 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
28fe0 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
28ff0 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
29000 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
29010 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
29020 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
29030 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
29040 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
29050 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
29060 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
29070 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
29080 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
29090 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
290a0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
290b0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
290c0 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
290d0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
290e0 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
290f0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
29100 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
29110 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
29120 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
29130 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
29140 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
29150 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
29160 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
29170 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
29180 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
29190 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
291a0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71  f the call to sq
291b0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
291c0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  ),.** sqlite3_bi
291d0 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71  nd_text(), or sq
291e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
291f0 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20  6() fails.  .** 
29200 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
29210 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
29220 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
29230 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
29240 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
29250 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
29260 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
29270 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
29280 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
29290 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
292a0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
292b0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
292c0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
292d0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
292e0 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
292f0 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
29300 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
29310 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
29320 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
29330 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
29340 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
29350 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
29360 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29370 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
29380 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
29390 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
293a0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
293b0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
293c0 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
293d0 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
293e0 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
293f0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
29400 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
29410 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
29420 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
29430 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
29440 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
29450 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
29460 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
29470 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
29480 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
29490 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
294a0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
294b0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
294c0 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
294d0 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
294e0 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
294f0 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
29500 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
29510 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
29520 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
29530 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
29540 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
29550 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
29560 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
29570 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
29580 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
29590 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
295a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
295b0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
295c0 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
295d0 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
295e0 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
295f0 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
29600 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
29610 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
29620 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
29630 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
29640 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
29650 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
29660 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
29670 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
29680 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
29690 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
296a0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
296b0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
296c0 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
296d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
296e0 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
296f0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
29700 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
29710 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
29720 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29730 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
29740 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
29750 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
29760 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
29770 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
29780 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
29790 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
297a0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
297b0 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
297c0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
297d0 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
297e0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
297f0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
29800 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
29810 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29820 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
29830 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
29840 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
29850 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
29860 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29870 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
29880 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
29890 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
298a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
298b0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
298c0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
298d0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
298e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
298f0 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
29900 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
29910 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45   double);.SQLITE
29920 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29930 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
29940 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
29950 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  t);.SQLITE_API i
29960 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
29970 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
29980 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
29990 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  3_int64);.SQLITE
299a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
299b0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
299c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
299d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
299e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
299f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29a00 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
29a10 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
29a20 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
29a30 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29a40 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
29a50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
29a60 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
29a70 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
29a80 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
29a90 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
29aa0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
29ab0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
29ac0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29ad0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29ae0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
29af0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
29b00 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
29b10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29b20 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
29b30 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
29b40 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
29b50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
29b60 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
29b70 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
29b80 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
29b90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
29ba0 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
29bb0 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
29bc0 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
29bd0 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
29be0 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
29bf0 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
29c00 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
29c10 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
29c20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
29c30 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
29c40 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
29c50 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
29c60 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
29c70 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
29c80 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
29c90 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
29ca0 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
29cb0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
29cc0 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
29cd0 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
29ce0 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
29cf0 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
29d00 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
29d10 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
29d20 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
29d30 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
29d40 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
29d50 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
29d60 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
29d70 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
29d80 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
29d90 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
29da0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29db0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
29dc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
29dd0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
29de0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
29df0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
29e00 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
29e10 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
29e20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
29e30 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
29e40 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
29e50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29e60 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29e70 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
29e80 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
29e90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
29ea0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
29eb0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
29ec0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29ed0 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
29ee0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
29ef0 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
29f00 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
29f10 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
29f20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
29f30 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
29f40 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
29f50 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
29f60 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
29f70 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
29f80 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
29f90 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
29fa0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
29fb0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
29fc0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
29fd0 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
29fe0 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
29ff0 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2a000 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2a010 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2a020 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2a030 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2a040 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2a050 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2a060 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2a070 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2a080 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2a090 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2a0a0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2a0b0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2a0c0 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2a0d0 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2a0e0 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2a0f0 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2a100 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2a110 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2a120 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2a130 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2a140 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2a150 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2a160 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2a170 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a180 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2a190 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2a1a0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2a1b0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2a1c0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2a1d0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2a1e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a1f0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2a200 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2a210 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2a220 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2a230 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2a240 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
2a250 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
2a260 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a270 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2a280 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
2a290 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
2a2a0 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
2a2b0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
2a2c0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
2a2d0 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
2a2e0 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
2a2f0 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
2a300 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
2a310 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
2a320 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
2a330 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2a340 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2a350 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
2a360 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
2a370 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
2a380 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
2a390 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
2a3a0 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
2a3b0 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
2a3c0 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
2a3d0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
2a3e0 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
2a3f0 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
2a400 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
2a410 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a420 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2a430 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2a440 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2a450 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2a460 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a470 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2a480 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2a490 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2a4a0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2a4b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2a4c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a4d0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
2a4e0 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
2a4f0 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
2a500 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2a510 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
2a520 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2a530 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ement.**.** ^Con
2a540 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
2a550 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
2a560 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2a570 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
2a580 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2a590 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
2a5a0 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
2a5b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a5c0 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
2a5d0 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
2a5e0 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
2a5f0 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
2a600 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2a610 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2a620 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2a630 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2a640 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2a650 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
2a660 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
2a670 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
2a680 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2a690 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
2a6a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2a6b0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2a6c0 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
2a6d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2a6e0 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
2a6f0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2a700 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
2a710 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
2a720 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
2a730 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
2a740 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
2a750 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  ta_count()].*/.S
2a760 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2a770 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2a780 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2a790 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2a7a0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
2a7b0 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
2a7c0 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
2a7d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2a7e0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
2a7f0 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
2a800 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
2a810 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2a820 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2a830 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
2a840 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a850 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
2a860 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2a870 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2a880 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2a890 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
2a8a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2a8b0 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
2a8c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2a8d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2a8e0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2a8f0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2a900 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
2a910 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a920 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
2a930 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
2a940 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
2a950 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2a960 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
2a970 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
2a980 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2a990 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
2a9a0 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
2a9b0 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
2a9c0 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
2a9d0 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
2a9e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a9f0 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
2aa00 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2aa10 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2aa20 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2aa30 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2aa40 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2aa50 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2aa60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2aa70 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2aa80 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2aa90 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
2aaa0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2aab0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
2aac0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2aad0 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
2aae0 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
2aaf0 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
2ab00 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
2ab10 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
2ab20 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
2ab30 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
2ab40 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
2ab50 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
2ab60 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
2ab70 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
2ab80 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2ab90 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2aba0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
2abb0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
2abc0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
2abd0 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
2abe0 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
2abf0 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
2ac00 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
2ac10 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
2ac20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
2ac30 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
2ac40 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
2ac50 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
2ac60 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
2ac70 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
2ac80 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49  he next..*/.SQLI
2ac90 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2aca0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2acb0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2acc0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51  tmt*, int N);.SQ
2acd0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2ace0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2acf0 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
2ad00 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2ad10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ad20 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
2ad30 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
2ad40 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ult.**.** ^These
2ad50 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
2ad60 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
2ad70 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
2ad80 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
2ad90 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
2ada0 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
2adb0 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
2adc0 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
2add0 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
2ade0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
2adf0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
2ae00 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
2ae10 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
2ae20 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
2ae30 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
2ae40 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2ae50 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
2ae60 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2ae70 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
2ae80 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
2ae90 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
2aea0 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
2aeb0 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
2aec0 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
2aed0 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
2aee0 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
2aef0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2af00 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2af10 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2af20 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
2af30 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
2af40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2af50 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2af60 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2af70 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2af80 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2af90 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2afa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2afb0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2afc0 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2afd0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
2afe0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
2aff0 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
2b000 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
2b010 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
2b020 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
2b030 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
2b040 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
2b050 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
2b060 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
2b070 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
2b080 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2b090 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
2b0a0 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
2b0b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2b0c0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2b0d0 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
2b0e0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
2b0f0 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
2b100 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
2b110 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
2b120 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2b130 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
2b140 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
2b150 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
2b160 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
2b170 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
2b180 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
2b190 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
2b1a0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
2b1b0 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
2b1c0 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
2b1d0 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
2b1e0 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
2b1f0 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
2b200 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2b210 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
2b220 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
2b230 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
2b240 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
2b250 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2b260 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
2b270 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
2b280 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
2b290 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
2b2a0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
2b2b0 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
2b2c0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
2b2d0 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
2b2e0 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
2b2f0 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
2b300 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
2b310 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
2b320 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
2b330 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
2b340 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
2b350 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
2b360 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2b370 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
2b380 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
2b390 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2b3a0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2b3b0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2b3c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2b3d0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2b3e0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2b3f0 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
2b400 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2b410 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2b420 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
2b430 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
2b440 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
2b450 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b460 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
2b470 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2b480 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2b490 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
2b4a0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2b4b0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2b4c0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
2b4d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2b4e0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
2b4f0 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
2b500 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
2b510 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
2b520 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b530 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
2b540 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
2b550 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2b560 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2b570 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49  defined..*/.SQLI
2b580 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2b590 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2b5a0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
2b5b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2b5c0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2b5d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2b5e0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2b5f0 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
2b600 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2b610 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2b620 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2b630 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
2b640 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b650 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2b660 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2b670 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2b680 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2b690 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2b6a0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2b6b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2b6c0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
2b6d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b6e0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2b6f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2b700 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2b710 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2b720 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2b730 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
2b740 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
2b750 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
2b760 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
2b770 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
2b780 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b790 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
2b7a0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
2b7b0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2b7c0 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
2b7d0 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
2b7e0 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
2b7f0 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
2b800 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
2b810 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
2b820 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2b830 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
2b840 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
2b850 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
2b860 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
2b870 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
2b880 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
2b890 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
2b8a0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2b8b0 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
2b8c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2b8d0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
2b8e0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2b8f0 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
2b900 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
2b910 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2b920 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
2b930 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
2b940 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
2b950 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
2b960 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
2b970 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
2b980 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2b990 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
2b9a0 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
2b9b0 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
2b9c0 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
2b9d0 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
2b9e0 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
2b9f0 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
2ba00 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
2ba10 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
2ba20 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
2ba30 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
2ba40 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
2ba50 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
2ba60 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
2ba70 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
2ba80 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
2ba90 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
2baa0 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
2bab0 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
2bac0 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
2bad0 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
2bae0 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
2baf0 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
2bb00 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
2bb10 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
2bb20 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
2bb30 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
2bb40 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
2bb50 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
2bb60 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
2bb70 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
2bb80 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
2bb90 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
2bba0 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
2bbb0 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ues..*/.SQLITE_A
2bbc0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2bbd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2bbe0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
2bbf0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2bc00 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2bc10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2bc20 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
2bc30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2bc40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2bc50 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
2bc60 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2bc70 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2bc80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2bc90 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2bca0 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2bcb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bcc0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2bcd0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2bce0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2bcf0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2bd00 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2bd10 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2bd20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2bd30 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2bd40 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2bd50 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2bd60 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2bd70 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2bd80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2bd90 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2bda0 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2bdb0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2bdc0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2bdd0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2bde0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2bdf0 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2be00 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2be10 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2be20 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2be30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2be40 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2be50 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2be60 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2be70 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2be80 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2be90 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2bea0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2beb0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2bec0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2bed0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2bee0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2bef0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2bf00 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2bf10 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2bf20 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2bf30 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2bf40 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2bf50 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2bf60 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2bf70 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2bf80 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2bf90 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2bfa0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2bfb0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2bfc0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2bfd0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2bfe0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2bff0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2c000 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2c010 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2c020 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2c030 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2c040 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2c050 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2c060 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2c070 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2c080 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2c090 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2c0a0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2c0b0 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2c0c0 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2c0d0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2c0e0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2c0f0 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2c100 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2c110 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2c120 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2c130 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2c140 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2c150 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2c160 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2c170 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2c180 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2c190 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2c1a0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2c1b0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2c1c0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2c1d0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2c1e0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2c1f0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2c200 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2c210 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2c220 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2c230 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2c240 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2c250 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2c260 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2c270 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2c280 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2c290 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2c2a0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2c2b0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2c2c0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2c2d0 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2c2e0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2c2f0 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2c300 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2c310 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2c320 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2c330 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2c340 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2c350 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2c360 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2c370 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2c380 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2c390 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2c3a0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2c3b0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2c3c0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2c3d0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2c3e0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2c3f0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2c400 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2c410 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2c420 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2c430 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2c440 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2c450 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2c460 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2c470 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2c480 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2c490 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2c4a0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2c4b0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2c4c0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2c4d0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2c4e0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2c4f0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2c500 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2c510 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2c520 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2c530 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2c540 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2c550 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2c560 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2c570 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c580 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2c590 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2c5a0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2c5b0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2c5c0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2c5d0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2c5e0 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2c5f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2c600 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2c610 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2c620 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2c630 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2c640 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2c650 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2c660 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2c670 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2c680 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2c690 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2c6a0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2c6b0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2c6c0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2c6d0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2c6e0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2c6f0 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2c700 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2c710 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2c720 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2c730 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2c740 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2c750 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2c760 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2c770 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2c780 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2c790 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2c7a0 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2c7b0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2c7c0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2c7d0 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2c7e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2c7f0 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2c800 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2c810 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2c820 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2c830 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2c840 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2c850 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2c860 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2c870 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2c880 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2c890 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2c8a0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2c8b0 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2c8c0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2c8d0 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2c8e0 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2c8f0 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2c900 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2c910 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2c920 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2c930 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2c940 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2c950 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2c960 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2c970 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2c980 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2c990 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2c9a0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2c9b0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2c9c0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2c9d0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2c9e0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2c9f0 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2ca00 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2ca10 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2ca20 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2ca30 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2ca40 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2ca50 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2ca60 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2ca70 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2ca80 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2ca90 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2caa0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2cab0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2cac0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2cad0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2cae0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2caf0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2cb00 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2cb10 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2cb20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2cb30 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2cb40 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2cb50 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2cb60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2cb70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2cb80 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2cb90 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2cba0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2cbb0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2cbc0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2cbd0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2cbe0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2cbf0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2cc00 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2cc10 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2cc20 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2cc30 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2cc40 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2cc50 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2cc60 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2cc70 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2cc80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2cc90 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2cca0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2ccb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ccc0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2ccd0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
2cce0 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
2ccf0 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
2cd00 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2cd10 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
2cd20 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
2cd30 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
2cd40 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
2cd50 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2cd60 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
2cd70 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2cd80 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
2cd90 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2cda0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2cdb0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2cdc0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
2cdd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2cde0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2cdf0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ce00 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2ce10 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
2ce20 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
2ce30 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2ce40 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2ce50 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
2ce60 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
2ce70 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
2ce80 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
2ce90 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
2cea0 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
2ceb0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2cec0 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
2ced0 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
2cee0 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
2cef0 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
2cf00 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
2cf10 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
2cf20 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2cf30 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
2cf40 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
2cf50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2cf60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2cf70 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2cf80 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2cf90 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
2cfa0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2cfb0 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2cfc0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
2cfd0 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
2cfe0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2cff0 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
2d000 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
2d010 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
2d020 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2d030 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2d040 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
2d050 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
2d060 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
2d070 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
2d080 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
2d090 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
2d0a0 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
2d0b0 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
2d0c0 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
2d0d0 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
2d0e0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
2d0f0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2d100 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2d110 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2d120 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2d130 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2d140 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2d150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2d160 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2d170 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2d180 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2d190 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2d1a0 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2d1b0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2d1c0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2d1d0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2d1e0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2d1f0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2d200 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2d210 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2d220 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2d230 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2d240 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2d250 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2d260 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2d270 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2d280 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2d290 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2d2a0 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2d2b0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2d2c0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2d2d0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2d2e0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2d2f0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2d300 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2d310 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2d320 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2d330 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2d340 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2d350 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2d360 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2d370 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2d380 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2d390 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2d3a0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2d3b0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2d3c0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2d3d0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2d3e0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2d3f0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2d400 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2d410 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2d420 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2d430 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2d440 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2d450 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d460 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2d470 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2d480 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2d490 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2d4a0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2d4b0 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2d4c0 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2d4d0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2d4e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2d4f0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2d500 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2d510 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2d520 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2d530 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2d540 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2d550 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2d560 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2d570 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2d580 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d590 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2d5a0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2d5b0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2d5c0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2d5d0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2d5e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2d5f0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2d600 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2d610 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2d620 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2d630 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2d640 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2d650 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2d660 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2d670 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2d680 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2d690 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2d6a0 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2d6b0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2d6c0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2d6d0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2d6e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2d6f0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2d700 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2d710 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2d720 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2d730 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2d740 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2d750 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2d760 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2d770 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2d780 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2d790 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2d7a0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2d7b0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2d7c0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2d7d0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2d7e0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2d7f0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2d800 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2d810 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2d820 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2d830 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2d840 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2d850 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2d860 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2d870 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2d880 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2d890 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2d8a0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2d8b0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2d8c0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2d8d0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2d8e0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2d8f0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2d900 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2d910 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2d920 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2d930 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2d940 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d950 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2d960 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2d970 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2d980 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2d990 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2d9a0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2d9b0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2d9c0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2d9d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2d9e0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2d9f0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2da00 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2da10 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2da20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2da30 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2da40 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2da50 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2da60 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2da70 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2da80 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2da90 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2daa0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2dab0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2dac0 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2dad0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2dae0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2daf0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2db00 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2db10 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2db20 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2db30 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2db40 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2db50 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2db60 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2db70 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2db80 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2db90 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2dba0 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2dbb0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2dbc0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2dbd0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2dbe0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2dbf0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2dc00 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2dc10 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2dc20 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2dc30 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2dc40 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2dc50 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2dc60 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2dc70 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2dc80 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2dc90 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2dca0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2dcb0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2dcc0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2dcd0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2dce0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2dcf0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2dd00 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2dd10 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2dd20 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2dd30 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2dd40 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2dd50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2dd60 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2dd70 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2dd80 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2dd90 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2dda0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2ddb0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2ddc0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2ddd0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2dde0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2ddf0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2de00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2de10 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2de20 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2de30 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2de40 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2de50 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2de60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2de70 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2de80 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2de90 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2dea0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2deb0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2dec0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2ded0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2dee0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2def0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2df00 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2df10 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2df20 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2df30 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2df40 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2df50 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2df60 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2df70 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2df80 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2df90 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2dfa0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2dfb0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2dfc0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2dfd0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2dfe0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2dff0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2e000 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2e010 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2e020 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2e030 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2e040 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2e050 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2e060 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e070 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2e080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e090 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2e0a0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2e0b0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2e0c0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2e0d0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2e0e0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2e0f0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2e100 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2e110 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2e120 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e130 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2e140 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2e150 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2e160 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2e170 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2e180 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2e190 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2e1a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e1b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2e1c0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2e1d0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2e1e0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2e1f0 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65  s zero terminate
2e200 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2e210 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2e220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2e230 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2e240 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2e250 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2e260 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2e270 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2e280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2e290 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2e2a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2e2b0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2e2c0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2e2d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2e2e0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2e2f0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2e300 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2e310 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2e320 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2e330 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2e340 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e350 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e360 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2e370 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2e380 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2e390 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2e3a0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2e3b0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2e3c0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2e3d0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2e3e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2e3f0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2e400 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2e410 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2e420 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2e430 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2e440 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2e450 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2e460 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2e470 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2e480 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2e490 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2e4a0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2e4b0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2e4c0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2e4d0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2e4e0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2e4f0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2e500 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2e510 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2e520 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2e530 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2e540 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2e550 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2e560 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2e570 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2e580 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2e590 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2e5a0 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2e5b0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2e5c0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2e5d0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2e5e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2e5f0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2e600 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2e610 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2e620 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2e630 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2e640 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2e650 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2e660 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2e670 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2e680 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2e690 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2e6a0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2e6b0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2e6c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2e6d0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2e6e0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2e6f0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2e700 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
2e710 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2e720 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2e730 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2e740 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2e750 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
2e760 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2e770 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2e780 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
2e790 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
2e7a0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2e7b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2e7c0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2e7d0 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
2e7e0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
2e7f0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
2e800 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2e810 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2e820 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
2e830 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2e840 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2e850 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
2e860 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2e870 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
2e880 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
2e890 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2e8a0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2e8b0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2e8c0 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
2e8d0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2e8e0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2e8f0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
2e900 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2e910 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
2e920 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2e930 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
2e940 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2e950 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2e960 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2e970 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
2e980 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
2e990 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
2e9a0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
2e9b0 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
2e9c0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2e9d0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
2e9e0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2e9f0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
2ea00 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2ea10 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2ea20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2ea30 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2ea40 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2ea50 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2ea60 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2ea70 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2ea80 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2ea90 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2eaa0 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2eab0 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2eac0 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2ead0 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2eae0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2eaf0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2eb00 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2eb10 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2eb20 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2eb30 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2eb40 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2eb50 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2eb60 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2eb70 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2eb80 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2eb90 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2eba0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2ebb0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2ebc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2ebd0 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2ebe0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2ebf0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2ec00 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2ec10 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2ec20 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2ec30 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2ec40 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2ec50 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2ec60 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2ec70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ec80 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2ec90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2eca0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2ecb0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2ecc0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2ecd0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2ece0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2ecf0 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2ed00 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2ed10 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2ed20 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2ed30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2ed40 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2ed50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2ed60 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2ed70 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2ed80 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2ed90 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2eda0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2edb0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2edc0 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2edd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2ede0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2edf0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2ee00 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2ee10 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2ee20 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2ee30 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2ee40 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2ee50 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
2ee60 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
2ee70 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
2ee80 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
2ee90 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
2eea0 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
2eeb0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
2eec0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
2eed0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
2eee0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
2eef0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
2ef00 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
2ef10 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
2ef20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
2ef30 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
2ef40 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
2ef50 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
2ef60 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
2ef70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
2ef80 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
2ef90 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
2efa0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
2efb0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
2efc0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
2efd0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
2efe0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
2eff0 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
2f000 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
2f010 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2f020 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
2f030 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
2f040 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
2f050 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2f060 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
2f070 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2f080 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2f090 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2f0a0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2f0b0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2f0c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f0d0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2f0e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f0f0 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
2f100 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2f110 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
2f120 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2f130 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2f140 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
2f150 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f160 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
2f170 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2f180 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2f190 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
2f1a0 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
2f1b0 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
2f1c0 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
2f1d0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
2f1e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f1f0 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
2f200 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2f210 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
2f220 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
2f230 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
2f240 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
2f250 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f260 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2f270 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
2f280 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2f290 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f2a0 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
2f2b0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
2f2c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f2d0 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
2f2e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2f2f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
2f300 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
2f310 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
2f320 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
2f330 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
2f340 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
2f350 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
2f360 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
2f370 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2f380 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2f390 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2f3a0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
2f3b0 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
2f3c0 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
2f3d0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
2f3e0 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
2f3f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
2f400 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
2f410 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
2f420 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
2f430 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2f440 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
2f450 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
2f460 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
2f470 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2f480 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
2f490 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2f4a0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2f4b0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
2f4c0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
2f4d0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
2f4e0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
2f4f0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
2f500 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
2f510 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
2f520 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
2f530 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2f540 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
2f550 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
2f560 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2f570 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
2f580 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
2f590 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2f5a0 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  M].)^.*/.SQLITE_
2f5b0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2f5c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f5d0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2f5e0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2f5f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f610 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2f620 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2f630 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2f640 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2f650 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2f660 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2f670 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71  TE_API double sq
2f680 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
2f690 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2f6a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2f6b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f6c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
2f6d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f6e0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2f6f0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
2f700 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
2f710 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
2f720 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f730 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2f740 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2f750 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2f760 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2f770 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f780 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2f790 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2f7a0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
2f7b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f7c0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2f7d0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2f7e0 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
2f7f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f800 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
2f810 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
2f820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2f830 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2f840 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
2f850 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2f860 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
2f870 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
2f880 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2f890 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2f8a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2f8b0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
2f8c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f8d0 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
2f8e0 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
2f8f0 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
2f900 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
2f910 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
2f920 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
2f930 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
2f940 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
2f950 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
2f960 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
2f970 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
2f980 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2f990 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
2f9a0 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
2f9b0 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
2f9c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
2f9d0 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
2f9e0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2f9f0 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
2fa00 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
2fa10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fa20 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2fa30 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
2fa40 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
2fa50 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
2fa60 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
2fa70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fa80 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
2fa90 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
2faa0 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
2fab0 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
2fac0 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
2fad0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2fae0 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
2faf0 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
2fb00 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
2fb10 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
2fb20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
2fb30 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
2fb40 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
2fb50 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
2fb60 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2fb70 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
2fb80 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
2fb90 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
2fba0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2fbb0 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
2fbc0 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
2fbd0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
2fbe0 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
2fbf0 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
2fc00 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
2fc10 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
2fc20 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
2fc30 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
2fc40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fc50 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
2fc60 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
2fc70 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
2fc80 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2fc90 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2fca0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
2fcb0 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
2fcc0 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
2fcd0 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
2fce0 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
2fcf0 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
2fd00 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  ruption..*/.SQLI
2fd10 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2fd20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
2fd30 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2fd40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fd50 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
2fd60 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2fd70 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ject.**.** The s
2fd80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
2fd90 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
2fda0 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72  d to reset a [pr
2fdb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fdc0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b  ].** object back
2fdd0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
2fde0 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
2fdf0 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
2fe00 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74  ** ^Any SQL stat
2fe10 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
2fe20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
2fe30 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
2fe40 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
2fe50 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2fe60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2fe70 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
2fe80 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
2fe90 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
2fea0 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
2feb0 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
2fec0 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  gs..**.** ^The [
2fed0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2fee0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
2fef0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
2ff00 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
2ff10 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
2ff20 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
2ff30 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ogram..**.** ^If
2ff40 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2ff50 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2ff60 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2ff70 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2ff80 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
2ff90 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2ffa0 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
2ffb0 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73  NE],.** or if [s
2ffc0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2ffd0 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
2ffe0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
2fff0 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  S,.** then [sqli
30000 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
30010 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
30020 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
30030 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
30040 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
30050 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
30060 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
30070 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74  ement] S indicat
30080 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65  ed an error, the
30090 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  n.** [sqlite3_re
300a0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
300b0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
300c0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
300d0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
300e0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
300f0 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
30100 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
30110 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74  ** of any [sqlit
30120 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
30130 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
30140 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30150 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  t] S..*/.SQLITE_
30160 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
30170 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
30180 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
30190 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
301a0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
301b0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
301c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
301d0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
301e0 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
301f0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
30200 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30210 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
30220 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
30230 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30240 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
30250 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
30260 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
30270 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
30280 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
30290 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
302a0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
302b0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
302c0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
302d0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
302e0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
302f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
30300 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
30310 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
30320 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
30330 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30340 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
30350 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
30360 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
30370 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
30380 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
30390 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
303a0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
303b0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
303c0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
303d0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
303e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
303f0 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
30400 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
30410 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
30420 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30430 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
30440 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
30450 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
30460 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
30470 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
30480 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
30490 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
304a0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
304b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
304c0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
304d0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
304e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
304f0 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
30500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
30510 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
30520 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
30530 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
30540 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
30550 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
30560 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
30570 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
30580 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
30590 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
305a0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
305b0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
305c0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
305d0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
305e0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
305f0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
30600 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
30610 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
30620 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
30630 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
30640 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
30650 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
30660 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
30670 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30680 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
30690 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
306a0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
306b0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
306c0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
306d0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
306e0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
306f0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
30700 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
30710 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
30720 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
30730 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
30740 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
30750 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
30760 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
30770 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
30780 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
30790 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
307a0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
307b0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
307c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
307d0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
307e0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
307f0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
30800 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
30810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
30820 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
30830 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
30840 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
30850 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
30860 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
30870 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
30880 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
30890 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20  ameters.  Every 
308a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
308b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
308c0 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
308d0 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20  .** with UTF-8, 
308e0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
308f0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
30900 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
30910 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
30920 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
30930 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
30940 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
30950 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
30960 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
30970 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30980 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
30990 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
309a0 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
309b0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
309c0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
309d0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
309e0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
309f0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
30a00 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
30a10 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
30a20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
30a30 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
30a40 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
30a50 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
30a60 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
30a70 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
30a80 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
30a90 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
30aa0 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
30ab0 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
30ac0 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
30ad0 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
30ae0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
30af0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
30b00 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
30b10 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
30b20 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
30b30 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
30b40 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
30b50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30b60 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
30b70 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
30b80 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
30b90 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
30ba0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
30bb0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
30bc0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
30bd0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
30be0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
30bf0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
30c00 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
30c10 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
30c20 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
30c30 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
30c40 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
30c50 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
30c60 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
30c70 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
30c80 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
30c90 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
30ca0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
30cb0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
30cc0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
30cd0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
30ce0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
30cf0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
30d00 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
30d10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30d20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
30d30 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
30d40 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
30d50 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
30d60 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
30d70 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
30d80 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
30d90 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
30da0 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
30db0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
30dc0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
30dd0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
30de0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
30df0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30e00 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
30e10 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
30e20 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
30e30 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
30e40 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
30e50 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
30e60 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
30e70 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
30e80 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
30e90 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
30ea0 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
30eb0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
30ec0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
30ed0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
30ee0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
30ef0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
30f00 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
30f10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30f20 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
30f30 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
30f40 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
30f50 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
30f60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
30f70 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
30f80 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
30f90 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
30fa0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
30fb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
30fc0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
30fd0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
30fe0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
30ff0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31000 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
31010 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
31020 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
31030 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
31040 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
31050 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
31060 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
31070 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
31080 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
31090 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
310a0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
310b0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
310c0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
310d0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
310e0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
310f0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
31100 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
31110 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
31120 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
31130 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
31140 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
31150 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
31160 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
31170 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
31180 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
31190 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
311a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
311b0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
311c0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
311d0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
311e0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
311f0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
31200 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
31210 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
31220 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
31230 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
31240 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
31250 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
31260 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
31270 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
31280 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
31290 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
312a0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
312b0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
312c0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
312d0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
312e0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
312f0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
31300 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
31310 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
31320 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
31330 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
31340 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31350 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
31360 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
31370 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31380 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
31390 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
313a0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
313b0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
313c0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
313d0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
313e0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
313f0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
31400 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
31410 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
31420 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
31430 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
31440 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
31450 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
31460 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31470 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
31480 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
31490 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
314a0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
314b0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
314c0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
314d0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
314e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
314f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31500 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
31510 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31520 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
31530 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
31540 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
31550 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51  _context*).);.SQ
31560 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
31570 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31580 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
31590 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
315a0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
315b0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
315c0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
315d0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
315e0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
315f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
31600 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
31610 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
31620 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
31630 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
31640 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
31650 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
31660 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
31670 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
31680 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31690 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
316a0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
316b0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
316c0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
316d0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
316e0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
316f0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
31700 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
31710 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31720 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
31730 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
31740 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31750 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31760 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
31770 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31780 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
31790 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
317a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
317b0 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
317c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
317d0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
317e0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
317f0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
31800 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
31810 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
31820 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
31830 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31840 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
31850 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31860 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
31870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31880 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
31890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
318a0 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
318b0 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
318c0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
318d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
318e0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
318f0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
31900 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
31910 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
31920 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
31930 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
31940 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31950 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
31960 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
31970 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
31980 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
31990 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
319a0 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
319b0 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
319c0 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
319d0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
319e0 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
319f0 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
31a00 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
31a10 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
31a20 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
31a30 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
31a40 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
31a50 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
31a60 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
31a70 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
31a80 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
31a90 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
31aa0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
31ab0 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
31ac0 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68  tell you what th
31ad0 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
31ae0 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
31af0 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
31b00 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
31b10 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
31b20 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
31b30 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
31b40 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
31b50 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
31b60 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
31b70 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
31b80 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  mt*);.SQLITE_API
31b90 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
31ba0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
31bb0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
31bc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31bd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
31be0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
31bf0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
31c00 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
31c10 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
31c20 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
31c30 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
31c40 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
31c50 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
31c60 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
31c70 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
31c80 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
31c90 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
31ca0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
31cb0 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69  ,int),void*,sqli
31cc0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
31cd0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
31ce0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
31cf0 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
31d00 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a  eter Values.**.*
31d10 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
31d20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31d30 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
31d40 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
31d50 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
31d60 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
31d70 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
31d80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
31d90 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
31da0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
31db0 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
31dc0 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
31dd0 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
31de0 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
31df0 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
31e00 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
31e10 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31e20 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
31e30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31e40 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
31e50 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
31e60 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
31e70 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
31e80 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
31e90 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
31ea0 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
31eb0 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
31ec0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
31ed0 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
31ee0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
31ef0 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
31f00 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
31f10 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
31f20 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
31f30 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
31f40 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
31f50 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
31f60 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
31f70 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
31f80 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
31f90 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
31fa0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
31fb0 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
31fc0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31fd0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
31fe0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
31ff0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
32000 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
32010 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32020 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
32030 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
32040 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
32050 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
32060 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
32070 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
32080 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
32090 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
320a0 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65  except that  the
320b0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
320c0 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
320d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
320e0 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
320f0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
32100 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
32110 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
32120 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
32130 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
32140 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
32150 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
32160 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
32170 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
32180 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
32190 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
321a0 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
321b0 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
321c0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
321d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
321e0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
321f0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
32200 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
32210 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
32220 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
32230 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
32240 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
32250 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
32260 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
32270 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
32280 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
32290 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
322a0 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
322b0 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
322c0 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
322d0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
322e0 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
322f0 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
32300 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
32310 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
32320 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
32330 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
32340 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
32350 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
32360 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
32370 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
32380 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
32390 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
323a0 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
323b0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
323c0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
323d0 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
323e0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
323f0 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
32400 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
32410 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
32420 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
32430 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
32440 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
32450 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
32460 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
32470 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
32480 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
32490 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
324a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
324b0 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
324c0 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
324d0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
324e0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
324f0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
32500 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
32510 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
32520 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
32530 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
32540 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
32550 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
32560 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
32570 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
32580 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
32590 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
325a0 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
325b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
325c0 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
325d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
325e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
325f0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
32600 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32610 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
32620 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
32630 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
32640 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
32650 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
32660 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
32670 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
32680 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69  _API double sqli
32690 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
326a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
326b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
326c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
326d0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
326e0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
326f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
32700 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
32710 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32720 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
32730 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
32740 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
32750 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
32760 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
32770 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
32780 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
32790 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
327a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
327b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
327c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
327d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
327e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
327f0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
32800 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
32810 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32820 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
32830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
32840 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
32850 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
32860 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
32870 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
32880 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
32890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
328a0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
328b0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
328c0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
328d0 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
328e0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
328f0 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
32900 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
32910 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
32920 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
32930 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
32940 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
32950 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32960 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
32970 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
32980 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
32990 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
329a0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
329b0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
329c0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
329d0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
329e0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
329f0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
32a00 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
32a10 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
32a20 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
32a30 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
32a40 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
32a50 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
32a60 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
32a70 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
32a80 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
32a90 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
32aa0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
32ab0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
32ac0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
32ad0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
32ae0 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
32af0 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
32b00 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
32b10 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
32b20 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
32b30 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
32b40 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
32b50 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
32b60 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
32b70 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
32b80 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
32b90 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
32ba0 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
32bb0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
32bc0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
32bd0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
32be0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
32bf0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
32c00 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
32c10 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
32c20 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
32c30 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
32c40 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
32c50 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
32c60 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
32c70 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
32c80 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
32c90 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
32ca0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
32cb0 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
32cc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
32cd0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
32ce0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
32cf0 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
32d00 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
32d10 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32d20 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
32d30 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
32d40 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
32d50 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
32d60 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
32d70 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
32d80 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
32d90 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
32da0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
32db0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
32dc0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
32dd0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
32de0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
32df0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
32e00 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
32e10 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
32e20 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
32e30 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
32e40 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
32e50 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
32e60 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
32e70 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
32e80 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
32e90 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
32ea0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
32eb0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
32ec0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
32ed0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
32ee0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
32ef0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
32f00 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
32f10 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
32f20 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
32f30 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
32f40 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
32f50 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
32f60 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
32f70 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
32f80 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
32f90 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
32fa0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
32fb0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
32fc0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
32fd0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61   void *sqlite3_a
32fe0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32ff0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33000 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
33010 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33020 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
33030 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
33040 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
33050 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
33060 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
33070 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
33080 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
33090 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
330a0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
330b0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
330c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
330d0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
330e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
330f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
33100 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
33110 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
33120 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
33130 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
33140 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
33150 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
33160 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
33170 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
33180 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
33190 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
331a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
331b0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
331c0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
331d0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
331e0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
331f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
33200 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
33210 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
33220 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
33230 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
33240 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
33250 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
33260 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
33270 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
33280 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33290 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
332a0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
332b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
332c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
332d0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
332e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
332f0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
33300 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
33310 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
33320 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
33330 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
33340 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
33350 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
33360 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
33370 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33380 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33390 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
333a0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
333b0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
333c0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
333d0 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
333e0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
333f0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
33400 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
33410 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
33420 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
33430 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
33440 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
33450 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
33460 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
33470 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
33480 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
33490 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
334a0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
334b0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
334c0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
334d0 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
334e0 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
334f0 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
33500 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
33510 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
33520 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
33530 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
33540 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
33550 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
33560 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
33570 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
33580 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
33590 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
335a0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
335b0 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
335c0 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
335d0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
335e0 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
335f0 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
33600 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
33610 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
33620 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
33630 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
33640 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
33650 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
33660 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
33670 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
33680 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
33690 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
336a0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
336b0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
336c0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
336d0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
336e0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
336f0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
33700 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
33710 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
33720 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33730 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e   function. ^If n
33740 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
33750 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
33760 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
33770 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
33780 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
33790 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
337a0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
337b0 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
337c0 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
337d0 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
337e0 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
337f0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
33800 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
33810 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
33820 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
33830 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
33840 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
33850 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
33860 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
33870 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
33880 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
33890 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
338a0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
338b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
338c0 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
338d0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
338e0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
338f0 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
33900 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
33910 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
33920 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
33930 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   ^If it is not N
33940 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
33950 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
33960 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
33970 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
33980 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
33990 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
339a0 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
339b0 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
339c0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
339d0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
339e0 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
339f0 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
33a00 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
33a10 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
33a20 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
33a30 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
33a40 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
33a50 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
33a60 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
33a70 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
33a80 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
33a90 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  any time.  ^The 
33aa0 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
33ab0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
33ac0 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
33ad0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
33ae0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
33af0 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ropped..**.** ^(
33b00 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
33b10 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
33b20 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
33b30 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
33b40 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
33b50 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
33b60 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
33b70 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
33b80 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
33b90 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
33ba0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
33bb0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
33bc0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
33bd0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
33be0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
33bf0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
33c00 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
33c10 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
33c20 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
33c30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33c40 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
33c50 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
33c60 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
33c70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
33c80 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
33c90 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
33ca0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33cb0 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
33cc0 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
33cd0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
33ce0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
33cf0 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
33d00 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
33d10 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
33d20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
33d30 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
33d40 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
33d50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
33d60 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
33d70 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
33d80 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
33d90 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
33da0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
33db0 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
33dc0 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
33dd0 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
33de0 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
33df0 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
33e00 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
33e10 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
33e20 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
33e30 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
33e40 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
33e50 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
33e60 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
33e70 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
33e80 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
33e90 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
33ea0 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
33eb0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
33ec0 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
33ed0 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
33ee0 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
33ef0 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
33f00 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
33f10 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
33f20 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
33f30 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
33f40 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
33f50 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
33f60 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
33f70 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
33f80 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
33f90 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
33fa0 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
33fb0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
33fc0 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
33fd0 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
33fe0 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
33ff0 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
34000 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
34010 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
34020 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
34030 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
34040 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
34050 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
34060 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
34070 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34080 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
34090 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
340a0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
340b0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
340c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
340d0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
340e0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
340f0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
34100 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
34110 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
34120 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
34130 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
34140 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
34150 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
34160 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
34170 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
34180 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
34190 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
341a0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
341b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
341c0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
341d0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
341e0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
341f0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
34200 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34210 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
34220 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
34230 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
34240 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
34250 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
34260 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
34270 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
34280 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
34290 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
342a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
342b0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
342c0 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
342d0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
342e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
342f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
34300 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
34310 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
34320 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
34330 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
34340 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
34350 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
34360 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
34370 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34380 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
34390 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
343a0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
343b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
343c0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
343d0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
343e0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
343f0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
34400 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
34410 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34420 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
34430 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34440 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
34450 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
34460 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
34470 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
34480 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
34490 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
344a0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
344b0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
344c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
344d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
344e0 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
344f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
34500 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
34510 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
34520 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
34530 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
34540 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
34550 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
34560 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34570 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
34580 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
34590 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
345a0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
345b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
345c0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
345d0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
345e0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
345f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34600 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34610 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
34620 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
34630 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
34640 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
34650 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
34660 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
34670 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
34680 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
34690 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
346a0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
346b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
346c0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
346d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
346e0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
346f0 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
34700 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
34710 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
34720 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
34730 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
34740 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
34750 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
34760 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34770 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
34780 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34790 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
347a0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
347b0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
347c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
347d0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
347e0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
347f0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
34800 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
34810 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
34820 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
34830 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
34840 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
34850 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34860 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
34870 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
34880 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
34890 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
348a0 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
348b0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
348c0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
348d0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
348e0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
348f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
34900 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
34910 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
34920 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
34930 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
34940 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
34950 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
34960 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
34970 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34980 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
34990 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
349a0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
349b0 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
349c0 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
349d0 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
349e0 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
349f0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
34a00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34a10 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
34a20 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
34a30 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
34a40 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
34a50 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
34a60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
34a70 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
34a80 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34a90 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
34aa0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
34ab0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
34ac0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34ad0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34ae0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
34af0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
34b00 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
34b10 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
34b20 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
34b30 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
34b40 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
34b50 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
34b60 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
34b70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34b80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
34b90 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
34ba0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
34bb0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
34bc0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
34bd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34be0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
34bf0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
34c00 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
34c10 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34c20 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34c30 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
34c40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34c50 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
34c60 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
34c70 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
34c80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34c90 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
34ca0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34cb0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
34cc0 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
34cd0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
34ce0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34cf0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34d00 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
34d10 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
34d20 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
34d30 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
34d40 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
34d50 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
34d60 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
34d70 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
34d80 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
34d90 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
34da0 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
34db0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
34dc0 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
34dd0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
34de0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34df0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
34e00 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
34e10 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
34e20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
34e30 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34e40 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
34e50 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
34e60 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
34e70 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
34e80 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
34e90 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
34ea0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
34eb0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
34ec0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
34ed0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34ee0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
34ef0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
34f00 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
34f10 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
34f20 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
34f30 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
34f40 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
34f50 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
34f60 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
34f70 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
34f80 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
34f90 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
34fa0 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
34fb0 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
34fc0 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
34fd0 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
34fe0 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
34ff0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
35000 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
35010 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
35020 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
35030 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
35040 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
35050 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
35060 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
35070 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
35080 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
35090 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
350a0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
350b0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
350c0 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
350d0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
350e0 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
350f0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
35100 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
35110 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
35120 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
35130 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
35140 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
35150 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
35160 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
35170 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
35180 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
35190 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
351a0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
351b0 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
351c0 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
351d0 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
351e0 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
351f0 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
35200 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
35210 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
35220 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
35230 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
35240 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35250 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35260 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
35270 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
35280 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
35290 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
352a0 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
352b0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
352c0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
352d0 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
352e0 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
352f0 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
35300 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
35310 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
35320 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
35330 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
35340 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
35350 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
35360 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
35370 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
35380 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
35390 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
353a0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
353b0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
353c0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
353d0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
353e0 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
353f0 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
35400 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
35410 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
35420 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
35430 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
35440 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
35450 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
35460 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
35470 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
35480 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
35490 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
354a0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
354b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
354c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
354d0 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
354e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
354f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
35500 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
35510 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
35520 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
35530 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
35540 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
35550 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
35560 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
35570 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
35580 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
35590 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
355a0 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
355b0 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
355c0 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
355d0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
355e0 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
355f0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
35600 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35610 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
35620 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
35630 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
35640 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
35650 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
35660 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
35670 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
35680 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
35690 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
356a0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
356b0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
356c0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
356d0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
356e0 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
356f0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
35700 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
35710 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
35720 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35730 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
35740 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
35750 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
35760 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
35770 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
35780 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
35790 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
357a0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
357b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
357c0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
357d0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
357e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
357f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35800 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
35810 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
35820 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  e);.SQLITE_API v
35830 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35840 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
35850 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
35860 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51   char*, int);.SQ
35870 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
35880 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35890 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
358a0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
358b0 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
358c0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
358d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
358e0 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
358f0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
35900 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
35910 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
35920 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
35930 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
35940 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
35950 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
35960 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35970 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
35980 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
35990 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
359a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
359b0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
359c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
359d0 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
359e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
359f0 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  e3_int64);.SQLIT
35a00 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
35a10 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
35a20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35a30 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35a40 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35a50 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
35a60 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
35a70 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
35a80 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
35a90 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
35aa0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35ab0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35ac0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
35ad0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
35ae0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
35af0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
35b00 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
35b10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35b20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
35b30 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
35b40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35b50 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35b60 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
35b70 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35b80 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
35b90 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
35ba0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
35bb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
35bc0 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
35bd0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
35be0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
35bf0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
35c00 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
35c10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35c20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
35c30 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
35c40 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
35c50 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  quences.**.** ^T
35c60 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
35c70 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
35c80 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
35c90 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
35ca0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
35cb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35cc0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
35cd0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
35ce0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
35cf0 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
35d00 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
35d10 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
35d20 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35d30 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
35d40 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35d50 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
35d60 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
35d70 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
35d80 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
35d90 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35da0 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
35db0 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
35dc0 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
35dd0 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
35de0 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
35df0 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
35e00 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
35e10 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
35e20 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
35e30 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
35e40 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
35e50 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
35e60 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
35e70 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
35e80 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
35e90 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
35ea0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
35eb0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
35ec0 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
35ed0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
35ee0 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
35ef0 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
35f00 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
35f10 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
35f20 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
35f30 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
35f40 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35f50 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
35f60 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
35f70 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
35f80 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
35f90 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
35fa0 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
35fb0 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
35fc0 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
35fd0 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
35fe0 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
35ff0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
36000 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
36010 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
36020 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
36030 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
36040 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
36050 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
36060 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
36070 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
36080 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
36090 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
360a0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
360b0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
360c0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
360d0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
360e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
360f0 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
36100 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
36110 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
36120 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
36130 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
36140 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
36150 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
36160 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
36170 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
36180 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
36190 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
361a0 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
361b0 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
361c0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
361d0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
361e0 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
361f0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
36200 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
36210 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
36220 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
36230 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
36240 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
36250 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
36260 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
36270 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
36280 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
36290 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
362a0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
362b0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
362c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
362d0 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
362e0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
362f0 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
36300 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
36310 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
36320 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
36330 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
36340 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
36350 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
36360 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
36370 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
36380 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
36390 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
363a0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
363b0 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
363c0 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
363d0 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
363e0 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
363f0 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
36400 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
36410 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
36420 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
36430 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  ust always retur
36440 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65  n the same answe
36450 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73  r.** given the s
36460 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20  ame inputs.  If 
36470 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c  two or more coll
36480 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
36490 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a  are registered.*
364a0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f  * to the same co
364b0 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73  llation name (us
364c0 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54  ing different eT
364d0 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74  extRep values) t
364e0 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20  hen all.** must 
364f0 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65  give an equivale
36500 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69  nt answer when i
36510 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69  nvoked with equi
36520 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a  valent strings..
36530 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** The collating
36540 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f   function must o
36550 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  bey the followin
36560 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72  g properties for
36570 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20   all.** strings 
36580 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a  A, B, and C:.**.
36590 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
365a0 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d  If A==B then B==
365b0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  A..** <li> If A=
365c0 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e  =B and B==C then
365d0 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   A==C..** <li> I
365e0 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26  f A&lt;B THEN B&
365f0 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  gt;A..** <li> If
36600 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74   A&lt;B and B&lt
36610 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a  ;C then A&lt;C..
36620 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
36630 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  f a collating fu
36640 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79  nction fails any
36650 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f   of the above co
36660 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
36670 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20  at.** collating 
36680 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67  function is  reg
36690 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64  istered and used
366a0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
366b0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
366c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
366d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
366e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
366f0 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
36700 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
36710 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
36720 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69   with the additi
36730 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73  on that the xDes
36740 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
36750 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67   invoked on pArg
36760 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c   when.** the col
36770 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
36780 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  is deleted..** ^
36790 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  Collating functi
367a0 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ons are deleted 
367b0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
367c0 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
367d0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68  r.** calls to th
367e0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
367f0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
36800 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64  r when the.** [d
36810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36820 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73  on] is closed us
36830 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
36840 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  se()]..**.** ^Th
36850 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
36860 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75  ack is <u>not</u
36870 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20  > called if the 
36880 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
36890 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
368a0 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  ) function fails
368b0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
368c0 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  that invoke.** s
368d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
368e0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74  llation_v2() wit
368f0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65  h a non-NULL xDe
36900 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73  stroy argument s
36910 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20  hould .** check 
36920 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
36930 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74  and dispose of t
36940 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
36950 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ata pointer.** t
36960 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72  hemselves rather
36970 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20   than expecting 
36980 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77  SQLite to deal w
36990 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e  ith it for them.
369a0 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66  .** This is diff
369b0 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79  erent from every
369c0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
369d0 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e  terface.  The in
369e0 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20  consistency .** 
369f0 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62  is unfortunate b
36a00 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  ut cannot be cha
36a10 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  nged without bre
36a20 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20  aking backwards 
36a30 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
36a40 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  y..**.** See als
36a50 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
36a60 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
36a70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
36a80 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
36a90 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
36aa0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
36ab0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
36ac0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
36ad0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
36ae0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
36af0 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
36b00 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
36b10 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
36b20 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
36b30 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51  nst void*).);.SQ
36b40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
36b50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36b60 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
36b70 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
36b80 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
36b90 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
36ba0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
36bb0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
36bc0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36bd0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36be0 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
36bf0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
36c00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
36c10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36c20 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
36c30 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
36c40 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
36c50 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
36c60 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
36c70 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
36c80 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
36c90 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
36ca0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
36cb0 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
36cc0 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
36cd0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76  cks.**.** ^To av
36ce0 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
36cf0 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
36d00 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
36d10 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
36d20 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
36d30 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
36d40 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
36d50 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
36d60 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  th the.** [datab
36d70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36d80 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
36d90 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
36da0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
36db0 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
36dc0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uired..**.** ^If
36dd0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
36de0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
36df0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
36e00 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
36e10 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
36e20 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
36e30 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
36e40 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
36e50 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
36e60 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
36e70 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65  TF-8. ^If sqlite
36e80 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36e90 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
36ea0 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
36eb0 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
36ec0 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
36ed0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
36ee0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69  ** ^A call to ei
36ef0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65  ther function re
36f00 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74  places the exist
36f10 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65  ing collation-ne
36f20 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  eded callback..*
36f30 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20  *.** ^(When the 
36f40 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
36f50 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
36f60 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
36f70 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
36f80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
36f90 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
36fa0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
36fb0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
36fc0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
36fd0 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
36fe0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
36ff0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
37000 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
37010 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
37020 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
37030 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
37040 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
37050 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
37060 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
37070 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
37080 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
37090 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
370a0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
370b0 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
370c0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
370d0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
370e0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
370f0 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a  n sequence.)^.**
37100 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
37110 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
37120 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
37130 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
37140 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
37150 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37160 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
37170 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
37180 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
37190 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
371a0 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  lation_v2()]..*/
371b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
371c0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
371d0 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
371e0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
371f0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
37200 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
37210 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
37220 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  r*).);.SQLITE_AP
37230 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
37240 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
37250 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
37260 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
37270 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
37280 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
37290 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
372a0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
372b0 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
372c0 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
372d0 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
372e0 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
372f0 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
37300 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
37310 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
37320 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
37330 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
37340 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
37350 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
37360 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
37370 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
37380 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
37390 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
373a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
373b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
373c0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
373d0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
373e0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
373f0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
37400 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
37410 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
37420 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
37430 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
37440 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
37450 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
37460 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
37470 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
37480 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
37490 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
374a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
374b0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
374c0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
374d0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
374e0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
374f0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
37500 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
37510 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
37520 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
37530 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
37540 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
37550 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
37560 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
37570 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
37580 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
37590 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
375a0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
375b0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
375c0 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
375d0 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e   a SEE database.
375e0 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
375f0 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
37600 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73  the SEE routines
37610 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53   will work..*/.S
37620 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
37630 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
37640 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
37650 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
37660 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
37670 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
37680 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
37690 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
376a0 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
376b0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
376c0 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
376d0 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
376e0 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
376f0 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
37700 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
37710 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  l work..*/.SQLIT
37720 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
37730 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f  e3_activate_cero
37740 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  d(.  const char 
37750 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
37760 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
37770 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
37780 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
37790 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
377a0 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
377b0 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20  hort Time.**.** 
377c0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
377d0 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
377e0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
377f0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
37800 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
37810 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
37820 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
37830 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
37840 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
37850 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
37860 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
37870 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
37880 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
37890 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
378a0 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
378b0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
378c0 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
378d0 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
378e0 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
378f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
37900 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
37910 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
37920 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
37930 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
37940 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
37950 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d  **.** ^SQLite im
37960 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
37970 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
37980 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
37990 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
379a0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
379b0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
379c0 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20  If the xSleep() 
379d0 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
379e0 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
379f0 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
37a00 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f  correctly, or no
37a10 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74  t implemented at
37a20 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68  .** all, then th
37a30 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
37a40 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61  lite3_sleep() ma
37a50 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74  y deviate from t
37a60 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a  he description.*
37a70 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  * in the previou
37a80 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f  s paragraphs..*/
37a90 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
37aa0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
37ab0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
37ac0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
37ad0 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
37ae0 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
37af0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
37b00 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
37b10 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
37b20 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
37b30 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
37b40 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
37b50 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
37b60 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
37b70 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
37b80 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
37b90 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
37ba0 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
37bb0 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
37bc0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
37bd0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
37be0 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
37bf0 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
37c00 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
37c10 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
37c20 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
37c30 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
37c40 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
37c50 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
37c60 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
37c70 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
37c80 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
37c90 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
37ca0 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
37cb0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
37cc0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
37cd0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
37ce0 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
37cf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37d00 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
37d10 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
37d20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
37d30 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
37d40 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
37d50 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
37d60 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
37d70 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
37d80 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
37d90 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
37da0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
37db0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
37dc0 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
37dd0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
37de0 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
37df0 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
37e00 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
37e10 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
37e20 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
37e30 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
37e40 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
37e50 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
37e60 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
37e70 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
37e80 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
37e90 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
37ea0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
37eb0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
37ec0 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
37ed0 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
37ee0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
37ef0 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
37f00 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
37f10 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
37f20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
37f30 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
37f40 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
37f50 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
37f60 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
37f70 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
37f80 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
37f90 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
37fa0 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
37fb0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
37fc0 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
37fd0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
37fe0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
37ff0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
38000 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
38010 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
38020 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
38030 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
38040 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
38050 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  /.SQLITE_API cha
38060 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  r *sqlite3_temp_
38070 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
38080 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
38090 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74   For Auto-Commit
380a0 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44   Mode.** KEYWORD
380b0 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
380c0 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ode}.**.** ^The 
380d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
380e0 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
380f0 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
38100 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
38110 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
38120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
38130 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
38140 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
38150 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
38160 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .  ^Autocommit m
38170 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
38180 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ault..** ^Autoco
38190 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
381a0 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
381b0 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
381c0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
381d0 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
381e0 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
381f0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
38200 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
38210 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
38220 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
38230 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
38240 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
38250 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
38260 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
38270 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
38280 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
38290 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
382a0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
382b0 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
382c0 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
382d0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
382e0 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
382f0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
38300 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
38310 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
38320 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
38330 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
38340 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
38350 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
38360 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
38370 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
38380 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
38390 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
383a0 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
383b0 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
383c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
383d0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
383e0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
383f0 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
38400 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
38410 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
38420 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
38430 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
38440 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
38450 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38460 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62  : Find The Datab
38470 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
38480 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
38490 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  nt.**.** ^The sq
384a0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
384b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
384c0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
384d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
384e0 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
384f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
38500 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
38510 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63  ^The [database c
38520 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65  onnection].** re
38530 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
38540 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
38550 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
38560 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
38570 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
38580 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
38590 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
385a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
385b0 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
385c0 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
385d0 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
385e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
385f0 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
38600 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
38610 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
38620 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
38630 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
38640 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
38650 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72   the next prepar
38660 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed statement.**.
38670 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
38680 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
38690 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74  nter to the next
386a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
386b0 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70  ment] after.** p
386c0 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20  Stmt associated 
386d0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
386e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
386f0 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69  Db.  ^If pStmt i
38700 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74  s NULL.** then t
38710 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
38720 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
38730 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65  to the first pre
38740 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
38750 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
38760 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
38770 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20  connection pDb. 
38780 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64   ^If no prepared
38790 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61   statement.** sa
387a0 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64  tisfies the cond
387b0 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72  itions of this r
387c0 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72  outine, it retur
387d0 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  ns NULL..**.*