System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 5e21690d890baf0290e26969703502a308a228a7:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 38 2e 34 2e 20 20 42  ersion 3.8.4.  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 54 68 65  t LFS..**.** The
0b00: 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
0b10: 61 70 68 20 77 61 73 20 77 72 69 74 74 65 6e 20  aph was written 
0b20: 69 6e 20 32 30 30 35 2e 20 20 28 54 68 69 73 20  in 2005.  (This 
0b30: 70 61 72 61 67 72 61 70 68 20 69 73 20 77 72 69  paragraph is wri
0b40: 74 74 65 6e 0a 2a 2a 20 6f 6e 20 32 30 30 38 2d  tten.** on 2008-
0b50: 31 31 2d 32 38 2e 29 20 54 68 65 73 65 20 64 61  11-28.) These da
0b60: 79 73 2c 20 61 6c 6c 20 4c 69 6e 75 78 20 6b 65  ys, all Linux ke
0b70: 72 6e 65 6c 73 20 73 75 70 70 6f 72 74 20 6c 61  rnels support la
0b80: 72 67 65 20 66 69 6c 65 73 2c 20 73 6f 0a 2a 2a  rge files, so.**
0b90: 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 6f 62   you should prob
0ba0: 61 62 6c 79 20 6c 65 61 76 65 20 4c 46 53 20 65  ably leave LFS e
0bb0: 6e 61 62 6c 65 64 2e 20 20 42 75 74 20 73 6f 6d  nabled.  But som
0bc0: 65 20 65 6d 62 65 64 64 65 64 20 70 6c 61 74 66  e embedded platf
0bd0: 6f 72 6d 73 20 6d 69 67 68 74 0a 2a 2a 20 6c 61  orms might.** la
0be0: 63 6b 20 4c 46 53 20 69 6e 20 77 68 69 63 68 20  ck LFS in which 
0bf0: 63 61 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  case the SQLITE_
0c00: 44 49 53 41 42 4c 45 5f 4c 46 53 20 6d 61 63 72  DISABLE_LFS macr
0c10: 6f 20 6d 69 67 68 74 20 73 74 69 6c 6c 20 62 65  o might still be
0c20: 20 75 73 65 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53   useful..**.** S
0c30: 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 66  imilar is true f
0c40: 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46  or Mac OS X.  LF
0c50: 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72  S is only suppor
0c60: 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20  ted on Mac OS X 
0c70: 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a  9 and later..*/.
0c80: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44  #ifndef SQLITE_D
0c90: 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66  ISABLE_LFS.# def
0ca0: 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20  ine _LARGE_FILE 
0cb0: 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66        1.# ifndef
0cc0: 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49   _FILE_OFFSET_BI
0cd0: 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46  TS.#   define _F
0ce0: 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20  ILE_OFFSET_BITS 
0cf0: 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66  64.# endif.# def
0d00: 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53  ine _LARGEFILE_S
0d10: 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a  OURCE 1.#endif..
0d20: 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 57 2c  /*.** For MinGW,
0d30: 20 63 68 65 63 6b 20 74 6f 20 73 65 65 20 69 66   check to see if
0d40: 20 77 65 20 63 61 6e 20 69 6e 63 6c 75 64 65 20   we can include 
0d50: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20  the header file 
0d60: 63 6f 6e 74 61 69 6e 69 6e 67 20 69 74 73 0a 2a  containing its.*
0d70: 2a 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d  * version inform
0d80: 61 74 69 6f 6e 2c 20 61 6d 6f 6e 67 20 6f 74 68  ation, among oth
0d90: 65 72 20 74 68 69 6e 67 73 2e 20 20 4e 6f 72 6d  er things.  Norm
0da0: 61 6c 6c 79 2c 20 74 68 69 73 20 69 6e 74 65 72  ally, this inter
0db0: 6e 61 6c 20 4d 69 6e 47 57 0a 2a 2a 20 68 65 61  nal MinGW.** hea
0dc0: 64 65 72 20 66 69 6c 65 20 77 6f 75 6c 64 20 5b  der file would [
0dd0: 6f 6e 6c 79 5d 20 62 65 20 69 6e 63 6c 75 64 65  only] be include
0de0: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
0df0: 62 79 20 6f 74 68 65 72 20 4d 69 6e 47 57 20 68  by other MinGW h
0e00: 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 73 3b 20  eader.** files; 
0e10: 68 6f 77 65 76 65 72 2c 20 74 68 65 20 63 6f 6e  however, the con
0e20: 74 61 69 6e 65 64 20 76 65 72 73 69 6f 6e 20 69  tained version i
0e30: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6e 6f  nformation is no
0e40: 77 20 72 65 71 75 69 72 65 64 20 62 79 20 74 68  w required by th
0e50: 69 73 0a 2a 2a 20 68 65 61 64 65 72 20 66 69 6c  is.** header fil
0e60: 65 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  e to work around
0e70: 20 62 69 6e 61 72 79 20 63 6f 6d 70 61 74 69 62   binary compatib
0e80: 69 6c 69 74 79 20 69 73 73 75 65 73 20 28 73 65  ility issues (se
0e90: 65 20 62 65 6c 6f 77 29 20 61 6e 64 0a 2a 2a 20  e below) and.** 
0ea0: 74 68 69 73 20 69 73 20 74 68 65 20 6f 6e 6c 79  this is the only
0eb0: 20 6b 6e 6f 77 6e 20 77 61 79 20 74 6f 20 72 65   known way to re
0ec0: 6c 69 61 62 6c 79 20 6f 62 74 61 69 6e 20 69 74  liably obtain it
0ed0: 2e 20 20 54 68 69 73 20 65 6e 74 69 72 65 20 23  .  This entire #
0ee0: 69 66 20 62 6c 6f 63 6b 0a 2a 2a 20 77 6f 75 6c  if block.** woul
0ef0: 64 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 20  d be completely 
0f00: 75 6e 6e 65 63 65 73 73 61 72 79 20 69 66 20 74  unnecessary if t
0f10: 68 65 72 65 20 77 61 73 20 61 6e 79 20 6f 74 68  here was any oth
0f20: 65 72 20 77 61 79 20 6f 66 20 64 65 74 65 63 74  er way of detect
0f30: 69 6e 67 0a 2a 2a 20 4d 69 6e 47 57 20 76 69 61  ing.** MinGW via
0f40: 20 74 68 65 69 72 20 70 72 65 70 72 6f 63 65 73   their preproces
0f50: 73 6f 72 20 28 65 2e 67 2e 20 69 66 20 74 68 65  sor (e.g. if the
0f60: 79 20 63 75 73 74 6f 6d 69 7a 65 64 20 74 68 65  y customized the
0f70: 69 72 20 47 43 43 20 74 6f 20 64 65 66 69 6e 65  ir GCC to define
0f80: 0a 2a 2a 20 73 6f 6d 65 20 4d 69 6e 47 57 2d 73  .** some MinGW-s
0f90: 70 65 63 69 66 69 63 20 6d 61 63 72 6f 73 29 2e  pecific macros).
0fa0: 20 20 57 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67    When compiling
0fb0: 20 66 6f 72 20 4d 69 6e 47 57 2c 20 65 69 74 68   for MinGW, eith
0fc0: 65 72 20 74 68 65 0a 2a 2a 20 5f 48 41 56 45 5f  er the.** _HAVE_
0fd0: 4d 49 4e 47 57 5f 48 20 6f 72 20 5f 48 41 56 45  MINGW_H or _HAVE
0fe0: 5f 5f 4d 49 4e 47 57 5f 48 20 28 6e 6f 74 65 20  __MINGW_H (note 
0ff0: 74 68 65 20 65 78 74 72 61 20 75 6e 64 65 72 73  the extra unders
1000: 63 6f 72 65 29 20 6d 61 63 72 6f 20 6d 75 73 74  core) macro must
1010: 20 62 65 0a 2a 2a 20 64 65 66 69 6e 65 64 3b 20   be.** defined; 
1020: 6f 74 68 65 72 77 69 73 65 2c 20 64 65 74 65 63  otherwise, detec
1030: 74 69 6f 6e 20 6f 66 20 63 6f 6e 64 69 74 69 6f  tion of conditio
1040: 6e 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 4d  ns specific to M
1050: 69 6e 47 57 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  inGW will be.** 
1060: 64 69 73 61 62 6c 65 64 2e 0a 2a 2f 0a 23 69 66  disabled..*/.#if
1070: 20 64 65 66 69 6e 65 64 28 5f 48 41 56 45 5f 4d   defined(_HAVE_M
1080: 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64  INGW_H).# includ
1090: 65 20 22 6d 69 6e 67 77 2e 68 22 0a 23 65 6c 69  e "mingw.h".#eli
10a0: 66 20 64 65 66 69 6e 65 64 28 5f 48 41 56 45 5f  f defined(_HAVE_
10b0: 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c  _MINGW_H).# incl
10c0: 75 64 65 20 22 5f 6d 69 6e 67 77 2e 68 22 0a 23  ude "_mingw.h".#
10d0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72  endif../*.** For
10e0: 20 4d 69 6e 47 57 20 76 65 72 73 69 6f 6e 20 34   MinGW version 4
10f0: 2e 78 20 28 61 6e 64 20 68 69 67 68 65 72 29 2c  .x (and higher),
1100: 20 63 68 65 63 6b 20 74 6f 20 73 65 65 20 69 66   check to see if
1110: 20 74 68 65 20 5f 55 53 45 5f 33 32 42 49 54 5f   the _USE_32BIT_
1120: 54 49 4d 45 5f 54 0a 2a 2a 20 64 65 66 69 6e 65  TIME_T.** define
1130: 20 69 73 20 72 65 71 75 69 72 65 64 20 74 6f 20   is required to 
1140: 6d 61 69 6e 74 61 69 6e 20 62 69 6e 61 72 79 20  maintain binary 
1150: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
1160: 74 68 20 74 68 65 20 4d 53 56 43 20 72 75 6e 74  th the MSVC runt
1170: 69 6d 65 0a 2a 2a 20 6c 69 62 72 61 72 79 20 69  ime.** library i
1180: 6e 20 75 73 65 20 28 65 2e 67 2e 20 66 6f 72 20  n use (e.g. for 
1190: 57 69 6e 64 6f 77 73 20 58 50 29 2e 0a 2a 2f 0a  Windows XP)..*/.
11a0: 23 69 66 20 21 64 65 66 69 6e 65 64 28 5f 55 53  #if !defined(_US
11b0: 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54 29 20  E_32BIT_TIME_T) 
11c0: 26 26 20 21 64 65 66 69 6e 65 64 28 5f 55 53 45  && !defined(_USE
11d0: 5f 36 34 42 49 54 5f 54 49 4d 45 5f 54 29 20 26  _64BIT_TIME_T) &
11e0: 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28  & \.    defined(
11f0: 5f 57 49 4e 33 32 29 20 26 26 20 21 64 65 66 69  _WIN32) && !defi
1200: 6e 65 64 28 5f 57 49 4e 36 34 29 20 26 26 20 5c  ned(_WIN64) && \
1210: 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d  .    defined(__M
1220: 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49  INGW_MAJOR_VERSI
1230: 4f 4e 29 20 26 26 20 5f 5f 4d 49 4e 47 57 5f 4d  ON) && __MINGW_M
1240: 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 20 3e 3d 20  AJOR_VERSION >= 
1250: 34 20 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e  4 && \.    defin
1260: 65 64 28 5f 5f 4d 53 56 43 52 54 5f 5f 29 0a 23  ed(__MSVCRT__).#
1270: 20 64 65 66 69 6e 65 20 5f 55 53 45 5f 33 32 42   define _USE_32B
1280: 49 54 5f 54 49 4d 45 5f 54 0a 23 65 6e 64 69 66  IT_TIME_T.#endif
1290: 0a 0a 2f 2a 20 54 68 65 20 70 75 62 6c 69 63 20  ../* The public 
12a0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
12b0: 2e 20 20 54 68 65 20 5f 46 49 4c 45 5f 4f 46 46  .  The _FILE_OFF
12c0: 53 45 54 5f 42 49 54 53 20 6d 61 63 72 6f 20 6d  SET_BITS macro m
12d0: 75 73 74 20 61 70 70 65 61 72 0a 2a 2a 20 66 69  ust appear.** fi
12e0: 72 73 74 20 69 6e 20 51 4e 58 2e 20 20 41 6c 73  rst in QNX.  Als
12f0: 6f 2c 20 74 68 65 20 5f 55 53 45 5f 33 32 42 49  o, the _USE_32BI
1300: 54 5f 54 49 4d 45 5f 54 20 6d 61 63 72 6f 20 6d  T_TIME_T macro m
1310: 75 73 74 20 61 70 70 65 61 72 20 66 69 72 73 74  ust appear first
1320: 20 66 6f 72 0a 2a 2a 20 4d 69 6e 47 57 2e 0a 2a   for.** MinGW..*
1330: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1340: 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65  * Include sqlite
1350: 33 2e 68 20 69 6e 20 74 68 65 20 6d 69 64 64 6c  3.h in the middl
1360: 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e 68  e of sqliteInt.h
1370: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
1380: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1390: 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c  * Begin file sql
13a0: 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ite3.h *********
13b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13d0: 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70  /./*.** 2001 Sep
13e0: 74 65 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20  tember 15.**.** 
13f0: 54 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c  The author discl
1400: 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74  aims copyright t
1410: 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f  o this source co
1420: 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66  de.  In place of
1430: 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69  .** a legal noti
1440: 63 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c  ce, here is a bl
1450: 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20  essing:.**.**   
1460: 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64   May you do good
1470: 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a   and not evil..*
1480: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e  *    May you fin
1490: 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f  d forgiveness fo
14a0: 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66  r yourself and f
14b0: 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a  orgive others..*
14c0: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61  *    May you sha
14d0: 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72  re freely, never
14e0: 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61   taking more tha
14f0: 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a  n you give..**.*
1500: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1510: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1520: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1530: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1540: 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73  ********.** This
1550: 20 68 65 61 64 65 72 20 66 69 6c 65 20 64 65 66   header file def
1560: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
1570: 63 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 69  ce that the SQLi
1580: 74 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72  te library.** pr
1590: 65 73 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74  esents to client
15a0: 20 70 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61   programs.  If a
15b0: 20 43 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72   C-function, str
15c0: 75 63 74 75 72 65 2c 20 64 61 74 61 74 79 70 65  ucture, datatype
15d0: 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74  ,.** or constant
15e0: 20 64 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73   definition does
15f0: 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74   not appear in t
1600: 68 69 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69  his file, then i
1610: 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75  t is.** not a pu
1620: 62 6c 69 73 68 65 64 20 41 50 49 20 6f 66 20 53  blished API of S
1630: 51 4c 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63  QLite, is subjec
1640: 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
1650: 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61  out.** notice, a
1660: 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
1670: 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 70   referenced by p
1680: 72 6f 67 72 61 6d 73 20 74 68 61 74 20 75 73 65  rograms that use
1690: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
16a0: 6f 6d 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e  ome of the defin
16b0: 69 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  itions that are 
16c0: 69 6e 20 74 68 69 73 20 66 69 6c 65 20 61 72 65  in this file are
16d0: 20 6d 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65   marked as.** "e
16e0: 78 70 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45  xperimental".  E
16f0: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65  xperimental inte
1700: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61  rfaces are norma
1710: 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75  lly new.** featu
1720: 72 65 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64  res recently add
1730: 65 64 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57  ed to SQLite.  W
1740: 65 20 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70  e do not anticip
1750: 61 74 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74  ate changes.** t
1760: 6f 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  o experimental i
1770: 6e 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65  nterfaces but re
1780: 73 65 72 76 65 20 74 68 65 20 72 69 67 68 74 20  serve the right 
1790: 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68  to make minor ch
17a0: 61 6e 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65  anges.** if expe
17b0: 72 69 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20  rience from use 
17c0: 22 69 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75  "in the wild" su
17d0: 67 67 65 73 74 20 73 75 63 68 20 63 68 61 6e 67  ggest such chang
17e0: 65 73 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a  es are prudent..
17f0: 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69  **.** The offici
1800: 61 6c 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50  al C-language AP
1810: 49 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  I documentation 
1820: 66 6f 72 20 53 51 4c 69 74 65 20 69 73 20 64 65  for SQLite is de
1830: 72 69 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f  rived.** from co
1840: 6d 6d 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66  mments in this f
1850: 69 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20  ile.  This file 
1860: 69 73 20 74 68 65 20 61 75 74 68 6f 72 69 74 61  is the authorita
1870: 74 69 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f  tive source.** o
1880: 6e 20 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74  n how SQLite int
1890: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 70 70  erfaces are supp
18a0: 6f 73 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a  ose to operate..
18b0: 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  **.** The name o
18c0: 66 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65  f this file unde
18d0: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
18e0: 6d 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73  management is "s
18f0: 71 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20  qlite.h.in"..** 
1900: 54 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b  The makefile mak
1910: 65 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68  es some minor ch
1920: 61 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69  anges to this fi
1930: 6c 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65  le (such as inse
1940: 72 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72  rting.** the ver
1950: 73 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64  sion number) and
1960: 20 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d   changes its nam
1970: 65 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22  e to "sqlite3.h"
1980: 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74   as.** part of t
1990: 68 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73  he build process
19a0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51  ..*/.#ifndef _SQ
19b0: 4c 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65  LITE3_H_.#define
19c0: 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e   _SQLITE3_H_.#in
19d0: 63 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e  clude <stdarg.h>
19e0: 20 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66       /* Needed f
19f0: 6f 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f  or the definitio
1a00: 6e 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a  n of va_list */.
1a10: 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65  ./*.** Make sure
1a20: 20 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69   we can call thi
1a30: 73 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b  s stuff from C++
1a40: 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 78 74 65 72  ..*/.#if 0.exter
1a50: 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a 0a  n "C" {.#endif..
1a60: 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 65 20 61  ./*.** Add the a
1a70: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
1a80: 64 65 20 27 65 78 74 65 72 6e 27 0a 2a 2f 0a 23  de 'extern'.*/.#
1a90: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58  ifndef SQLITE_EX
1aa0: 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51  TERN.# define SQ
1ab0: 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65  LITE_EXTERN exte
1ac0: 72 6e 0a 23 65 6e 64 69 66 0a 0a 23 69 66 6e 64  rn.#endif..#ifnd
1ad0: 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20  ef SQLITE_API.# 
1ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50  define SQLITE_AP
1af0: 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a  I.#endif.../*.**
1b00: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
1b10: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
1b20: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
1b30: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
1b40: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
1b50: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
1b60: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
1b70: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
1b80: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
1b90: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
1ba0: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
1bb0: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
1bc0: 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  rt for backwards
1bd0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
1be0: 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61  y only.  Applica
1bf0: 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f  tion writers sho
1c00: 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61  uld be aware tha
1c10: 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61  t.** experimenta
1c20: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
1c30: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
1c40: 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65  ge in point rele
1c50: 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ases..**.** Thes
1c60: 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f  e macros used to
1c70: 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69   resolve to vari
1c80: 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d  ous kinds of com
1c90: 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74  piler magic that
1ca0: 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61  .** would genera
1cb0: 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61  te warning messa
1cc0: 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65  ges when they we
1cd0: 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68  re used.  But th
1ce0: 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d  at.** compiler m
1cf0: 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65  agic ended up ge
1d00: 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20  nerating such a 
1d10: 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65  flurry of bug re
1d20: 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65  ports.** that we
1d30: 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61   have taken it a
1d40: 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20  ll out and gone 
1d50: 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69  back to using si
1d60: 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63  mple.** noop mac
1d70: 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ros..*/.#define 
1d80: 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
1d90: 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  D.#define SQLITE
1da0: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f  _EXPERIMENTAL../
1db0: 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73  *.** Ensure thes
1dc0: 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e  e symbols were n
1dd0: 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f  ot defined by so
1de0: 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64  me previous head
1df0: 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64  er file..*/.#ifd
1e00: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ef SQLITE_VERSIO
1e10: 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  N.# undef SQLITE
1e20: 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a  _VERSION.#endif.
1e30: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
1e40: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75  RSION_NUMBER.# u
1e50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
1e60: 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69  ION_NUMBER.#endi
1e70: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1e80: 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
1e90: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
1ea0: 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28  Numbers.**.** ^(
1eb0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  The [SQLITE_VERS
1ec0: 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73  ION] C preproces
1ed0: 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65  sor macro in the
1ee0: 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65   sqlite3.h heade
1ef0: 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74  r.** evaluates t
1f00: 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1f10: 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53  al that is the S
1f20: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e  QLite version in
1f30: 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22   the.** format "
1f40: 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69  X.Y.Z" where X i
1f50: 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73  s the major vers
1f60: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61  ion number (alwa
1f70: 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69  ys 3 for.** SQLi
1f80: 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68  te3) and Y is th
1f90: 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20  e minor version 
1fa0: 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20  number and Z is 
1fb0: 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62  the release numb
1fc0: 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b  er.)^.** ^(The [
1fd0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1fe0: 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63  UMBER] C preproc
1ff0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f  essor macro reso
2000: 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67  lves to an integ
2010: 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  er.** with the v
2020: 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20  alue (X*1000000 
2030: 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68  + Y*1000 + Z) wh
2040: 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20  ere X, Y, and Z 
2050: 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  are the same.** 
2060: 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20  numbers used in 
2070: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
2080: 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .)^.** The SQLIT
2090: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
20a0: 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72   for any given r
20b0: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
20c0: 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65   will also.** be
20d0: 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
20e0: 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68   release from wh
20f0: 69 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65  ich it is derive
2100: 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c  d.  Either Y wil
2110: 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e  l.** be held con
2120: 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c  stant and Z will
2130: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20   be incremented 
2140: 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62  or else Y will b
2150: 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a  e incremented.**
2160: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72   and Z will be r
2170: 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a  eset to zero..**
2180: 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69 6f  .** Since versio
2190: 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65  n 3.6.18, SQLite
21a0: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
21b0: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
21c0: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
21d0: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
21e0: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
21f0: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
2200: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
2210: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
2220: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
2230: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
2240: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
2250: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
2260: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
2270: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
2280: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
2290: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
22a0: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
22b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
22c0: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
22d0: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
22e0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
22f0: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
2300: 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a  C) and an SHA1.*
2310: 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e  * hash of the en
2320: 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 65 65  tire source tree
2330: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2340: 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  : [sqlite3_libve
2350: 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  rsion()],.** [sq
2360: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
2370: 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c  _number()], [sql
2380: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 5d  ite3_sourceid()]
2390: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72  ,.** [sqlite_ver
23a0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
23b0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
23c0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
23d0: 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20  ITE_VERSION     
23e0: 20 20 20 22 33 2e 38 2e 34 22 0a 23 64 65 66 69     "3.8.4".#defi
23f0: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
2400: 4e 5f 4e 55 4d 42 45 52 20 33 30 30 38 30 30 34  N_NUMBER 3008004
2410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2420: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
2430: 32 30 31 34 2d 30 33 2d 30 37 20 31 34 3a 35 37  2014-03-07 14:57
2440: 3a 30 37 20 65 35 62 31 37 61 39 64 30 37 61 33  :07 e5b17a9d07a3
2450: 35 63 39 62 34 34 66 66 39 37 37 62 61 38 31 62  5c9b44ff977ba81b
2460: 39 33 64 37 34 35 64 32 36 61 31 31 22 0a 0a 2f  93d745d26a11"../
2470: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2480: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
2490: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
24a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
24b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71  ite3_version, sq
24c0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
24d0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
24e0: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
24f0: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
2500: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
2510: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
2520: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
2530: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
2540: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
2550: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
2560: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
2570: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2580: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
2590: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
25a0: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
25b0: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
25c0: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
25d0: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
25e0: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
25f0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
2600: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
2610: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
2620: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
2630: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
2640: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
2650: 72 2c 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75  r, and thus insu
2660: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
2670: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
2680: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
2690: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
26a0: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
26b0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
26c0: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
26d0: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
26e0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
26f0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
2700: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
2710: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
2720: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
2730: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
2740: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
2750: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
2760: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
2770: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
2780: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
2790: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
27a0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
27b0: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
27c0: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
27d0: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
27e0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
27f0: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
2800: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
2810: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
2820: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2830: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
2840: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
2850: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
2860: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
2870: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
2880: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
2890: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
28a0: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
28b0: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
28c0: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
28d0: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
28e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
28f0: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
2900: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
2910: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
2920: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
2930: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
2940: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
2950: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
2960: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2970: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
2980: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
2990: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
29a0: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
29b0: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
29c0: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
29d0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
29e0: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
29f0: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
2a00: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2a10: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
2a20: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
2a30: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
2a40: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2a50: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
2a60: 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f 56 45 52  n[] = SQLITE_VER
2a70: 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f 41 50 49  SION;.SQLITE_API
2a80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2a90: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
2aa0: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
2ab0: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2ac0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76  lite3_sourceid(v
2ad0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
2ae0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62   int sqlite3_lib
2af0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
2b00: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
2b10: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
2b20: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
2b30: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
2b40: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
2b50: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
2b60: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
2b70: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
2b80: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
2b90: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
2ba0: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
2bb0: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
2bc0: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
2bd0: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
2be0: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
2bf0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
2c00: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
2c10: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
2c20: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
2c30: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
2c40: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
2c60: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
2c70: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
2c80: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
2c90: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
2ca0: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
2cb0: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
2cc0: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
2cd0: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
2ce0: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
2cf0: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
2d00: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
2d10: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
2d20: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
2d30: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
2d40: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
2d50: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
2d60: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
2d70: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
2d80: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
2d90: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
2da0: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
2db0: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
2dc0: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
2dd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
2de0: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
2df0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
2e00: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
2e10: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
2e20: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
2e30: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
2e40: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
2e50: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
2e60: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
2e70: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
2e80: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
2e90: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
2ea0: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
2eb0: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
2ec0: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
2ed0: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
2ee0: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
2ef0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
2f00: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
2f10: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
2f20: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2f30: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
2f40: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
2f50: 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45  OptName);.SQLITE
2f60: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2f70: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
2f80: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
2f90: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
2fa0: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
2fb0: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
2fc0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
2fd0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
2fe0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2ff0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
3000: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
3010: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
3020: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
3030: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
3040: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
3050: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
3060: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
3070: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
3080: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
3090: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
30a0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
30b0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
30c0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
30d0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
30e0: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
30f0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
3100: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
3110: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
3120: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
3130: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
3140: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
3150: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
3160: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
3170: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
3180: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
3190: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
31a0: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
31b0: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
31c0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
31d0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
31e0: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
31f0: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
3200: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
3210: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
3220: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
3230: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
3240: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
3250: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
3260: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
3270: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
3280: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
3290: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
32a0: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
32b0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
32c0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
32d0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
32e0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
32f0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
3300: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
3310: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
3320: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
3330: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
3340: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
3350: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
3360: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
3370: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
3380: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
3390: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
33a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
33b0: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
33c0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
33d0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
33e0: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
33f0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
3400: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
3410: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
3420: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
3430: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
3440: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
3450: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
3460: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
3470: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
3480: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
3490: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
34a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
34b0: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
34c0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
34d0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
34e0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
34f0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
3500: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
3510: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
3520: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
3530: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
3540: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
3550: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
3560: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
3570: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
3580: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
3590: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
35a0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
35b0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
35c0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
35d0: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
35e0: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
35f0: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
3600: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
3610: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
3620: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
3630: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
3640: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
3650: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
3660: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
3670: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
3680: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
3690: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
36a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
36b0: 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  e(void);../*.** 
36c0: 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
36d0: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61  se Connection Ha
36e0: 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ndle.** KEYWORDS
36f0: 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  : {database conn
3700: 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73  ection} {databas
3710: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a  e connections}.*
3720: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53  *.** Each open S
3730: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69  QLite database i
3740: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  s represented by
3750: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
3760: 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20   instance of.** 
3770: 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63  the opaque struc
3780: 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69  ture named "sqli
3790: 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65  te3".  It is use
37a0: 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20  ful to think of 
37b0: 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f  an sqlite3.** po
37c0: 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65  inter as an obje
37d0: 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ct.  The [sqlite
37e0: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
37f0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
3800: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  nd.** [sqlite3_o
3810: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
3820: 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e  aces are its con
3830: 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b  structors, and [
3840: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
3850: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
3860: 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65  _close_v2()] are
3870: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73   its destructors
3880: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e  .  There are man
3890: 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72  y other.** inter
38a0: 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a  faces (such as.*
38b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
38c0: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
38d0: 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
38e0: 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  on()], and.** [s
38f0: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
3900: 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62  out()] to name b
3910: 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61  ut three) that a
3920: 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e  re methods on an
3930: 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65  .** sqlite3 obje
3940: 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ct..*/.typedef s
3950: 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71  truct sqlite3 sq
3960: 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lite3;../*.** CA
3970: 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49  PI3REF: 64-Bit I
3980: 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20  nteger Types.** 
3990: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
39a0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
39b0: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
39c0: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
39d0: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
39e0: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
39f0: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
3a00: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
3a10: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
3a20: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
3a30: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
3a40: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
3a50: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
3a60: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
3a70: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
3a80: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
3a90: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
3aa0: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
3ab0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
3ac0: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
3ad0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
3ae0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
3af0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nly..**.** ^The 
3b00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
3b10: 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74  d sqlite_int64 t
3b20: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69  ypes can store i
3b30: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a  nteger values.**
3b40: 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37   between -922337
3b50: 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e  2036854775808 an
3b60: 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34  d +9223372036854
3b70: 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65  775807 inclusive
3b80: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
3b90: 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71  e3_uint64 and sq
3ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
3bb0: 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65  s can store inte
3bc0: 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62  ger values .** b
3bd0: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38  etween 0 and +18
3be0: 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36  4467440737095516
3bf0: 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f  15 inclusive..*/
3c00: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49  .#ifdef SQLITE_I
3c10: 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65  NT64_TYPE.  type
3c20: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
3c30: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74  _TYPE sqlite_int
3c40: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
3c50: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e  signed SQLITE_IN
3c60: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
3c70: 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65  uint64;.#elif de
3c80: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20  fined(_MSC_VER) 
3c90: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52  || defined(__BOR
3ca0: 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64  LANDC__).  typed
3cb0: 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ef __int64 sqlit
3cc0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
3cd0: 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e  ef unsigned __in
3ce0: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  t64 sqlite_uint6
3cf0: 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64  4;.#else.  typed
3d00: 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ef long long int
3d10: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
3d20: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
3d30: 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  d long long int 
3d40: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
3d50: 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71  endif.typedef sq
3d60: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
3d70: 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65  e3_int64;.typede
3d80: 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  f sqlite_uint64 
3d90: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a  sqlite3_uint64;.
3da0: 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c  ./*.** If compil
3db0: 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73  ing for a proces
3dc0: 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66  sor that lacks f
3dd0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75  loating point su
3de0: 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69  pport,.** substi
3df0: 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72  tute integer for
3e00: 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e   floating-point.
3e10: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
3e20: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f  E_OMIT_FLOATING_
3e30: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64  POINT.# define d
3e40: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e  ouble sqlite3_in
3e50: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  t64.#endif../*.*
3e60: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73  * CAPI3REF: Clos
3e70: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43  ing A Database C
3e80: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
3e90: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ^The sqlite3_clo
3ea0: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  se() and sqlite3
3eb0: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 74  _close_v2() rout
3ec0: 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 63  ines are destruc
3ed0: 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  tors.** for the 
3ee0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
3ef0: 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  ..** ^Calls to s
3f00: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
3f10: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
3f20: 5f 76 32 28 29 20 72 65 74 75 72 6e 20 53 51 4c  _v2() return SQL
3f30: 49 54 45 5f 4f 4b 20 69 66 0a 2a 2a 20 74 68 65  ITE_OK if.** the
3f40: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3f50: 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c  t is successfull
3f60: 79 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20  y destroyed and 
3f70: 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  all associated.*
3f80: 2a 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20  * resources are 
3f90: 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a  deallocated..**.
3fa0: 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
3fb0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
3fc0: 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
3fd0: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72  h unfinalized pr
3fe0: 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
3ff0: 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68  ents or unfinish
4000: 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  ed sqlite3_backu
4010: 70 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73  p objects then s
4020: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a  qlite3_close().*
4030: 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65  * will leave the
4040: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4050: 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65  tion open and re
4060: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
4070: 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  Y]..** ^If sqlit
4080: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
4090: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66   called with unf
40a0: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65  inalized prepare
40b0: 64 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d statements.** 
40c0: 61 6e 64 20 75 6e 66 69 6e 69 73 68 65 64 20 73  and unfinished s
40d0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20  qlite3_backups, 
40e0: 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
40f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63  e connection bec
4100: 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61  omes.** an unusa
4110: 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69  ble "zombie" whi
4120: 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  ch will automati
4130: 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63  cally be dealloc
4140: 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a  ated when the.**
4150: 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73   last prepared s
4160: 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61  tatement is fina
4170: 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73  lized or the las
4180: 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  t sqlite3_backup
4190: 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e   is.** finished.
41a0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c    The sqlite3_cl
41b0: 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ose_v2() interfa
41c0: 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ce is intended f
41d0: 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68  or use with.** h
41e0: 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68  ost languages th
41f0: 61 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63  at are garbage c
4200: 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68  ollected, and wh
4210: 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e  ere the order in
4220: 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75   which.** destru
4230: 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64  ctors are called
4240: 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a   is arbitrary..*
4250: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
4260: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
4270: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
4280: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
4290: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
42a0: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  ,.** [sqlite3_bl
42b0: 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65  ob_close | close
42c0: 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64  ] all [BLOB hand
42d0: 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73  les], and .** [s
42e0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69  qlite3_backup_fi
42f0: 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61  nish | finish] a
4300: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ll [sqlite3_back
4310: 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f  up] objects asso
4320: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
4330: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
4340: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74  ect prior to att
4350: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65  empting to close
4360: 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49   the object.  ^I
4370: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f  f.** sqlite3_clo
4380: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
4390: 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65  d on a [database
43a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
43b0: 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f  t still has.** o
43c0: 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70  utstanding [prep
43d0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
43e0: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
43f0: 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c  , and/or.** [sql
4400: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
4410: 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74  ects then it ret
4420: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 62  urns SQLITE_OK b
4430: 75 74 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74  ut the deallocat
4440: 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72  ion.** of resour
4450: 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20  ces is deferred 
4460: 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61  until all [prepa
4470: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
4480: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
4490: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
44a0: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
44b0: 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f   are also destro
44c0: 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  yed..**.** ^If a
44d0: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
44e0: 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ct is destroyed 
44f0: 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74  while a transact
4500: 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20  ion is open,.** 
4510: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
4520: 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
4530: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
4540: 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65  .** The C parame
4550: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
4560: 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73  close(C)] and [s
4570: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
4580: 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  C)].** must be e
4590: 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  ither a NULL.** 
45a0: 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73  pointer or an [s
45b0: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
45c0: 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a  ointer obtained.
45d0: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
45e0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
45f0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
4600: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
4610: 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74  n_v2()], and not
4620: 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73   previously clos
4630: 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  ed..** ^Calling 
4640: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
4650: 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  or sqlite3_close
4660: 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c  _v2() with a NUL
4670: 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67  L pointer.** arg
4680: 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c  ument is a harml
4690: 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51  ess no-op..*/.SQ
46a0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
46b0: 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74  ite3_close(sqlit
46c0: 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  e3*);.SQLITE_API
46d0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
46e0: 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b  se_v2(sqlite3*);
46f0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ../*.** The type
4700: 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20   for a callback 
4710: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69  function..** Thi
4720: 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20  s is legacy and 
4730: 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20  deprecated.  It 
4740: 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20  is included for 
4750: 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f  historical.** co
4760: 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20  mpatibility and 
4770: 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65  is not documente
4780: 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e  d..*/.typedef in
4790: 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c  t (*sqlite3_call
47a0: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
47b0: 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b  char**, char**);
47c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
47d0: 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79  : One-Step Query
47e0: 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72   Execution Inter
47f0: 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  face.**.** The s
4800: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e  qlite3_exec() in
4810: 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e  terface is a con
4820: 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72  venience wrapper
4830: 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
4840: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
4850: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
4860: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
4870: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a  3_finalize()],.*
4880: 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e  * that allows an
4890: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
48a0: 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61  run multiple sta
48b0: 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a  tements of SQL.*
48c0: 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67  * without having
48d0: 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66   to use a lot of
48e0: 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20   C code. .**.** 
48f0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65  ^The sqlite3_exe
4900: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 75  c() interface ru
4910: 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  ns zero or more 
4920: 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a  UTF-8 encoded,.*
4930: 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
4940: 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  rate SQL stateme
4950: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20  nts passed into 
4960: 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
4970: 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74  ,.** in the cont
4980: 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ext of the [data
4990: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
49a0: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 74   passed in as it
49b0: 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  s 1st.** argumen
49c0: 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  t.  ^If the call
49d0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66  back function of
49e0: 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e   the 3rd argumen
49f0: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
4a00: 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55  exec() is not NU
4a10: 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69  LL, then it is i
4a20: 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20  nvoked for each 
4a30: 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f  result row.** co
4a40: 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20  ming out of the 
4a50: 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74  evaluated SQL st
4a60: 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20  atements.  ^The 
4a70: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  4th argument to.
4a80: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
4a90: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
4aa0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
4ab0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
4ac0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
4ad0: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
4ae0: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
4af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4b00: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
4b10: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
4b20: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
4b30: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
4b40: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
4b50: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
4b60: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
4b70: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
4b80: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
4b90: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
4ba0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
4bb0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
4bc0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
4bd0: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
4be0: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
4bf0: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
4c00: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
4c10: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
4c20: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
4c30: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
4c40: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
4c50: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
4c60: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
4c70: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4c80: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
4c90: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
4ca0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
4cb0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
4cc0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
4cd0: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
4ce0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
4cf0: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
4d00: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
4d10: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
4d20: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
4d30: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
4d40: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
4d50: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
4d60: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
4d70: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
4d80: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
4d90: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
4da0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4db0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
4dc0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
4dd0: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
4de0: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
4df0: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
4e00: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
4e10: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
4e20: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
4e30: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
4e40: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
4e50: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
4e60: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
4e70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
4e80: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
4e90: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
4ea0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
4eb0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
4ec0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
4ed0: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
4ee0: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
4ef0: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
4f00: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
4f10: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
4f20: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
4f30: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
4f40: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
4f50: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
4f60: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
4f70: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
4f80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
4f90: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
4fa0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
4fb0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
4fc0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
4fd0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
4fe0: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
4ff0: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
5000: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
5010: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
5020: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
5030: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
5040: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
5050: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
5060: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
5070: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
5080: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
5090: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
50a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
50b0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
50c0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
50d0: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
50e0: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
50f0: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
5100: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
5110: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
5120: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
5130: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
5140: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
5150: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
5160: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
5170: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
5180: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
5190: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
51a0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
51b0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
51c0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
51d0: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
51e0: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
51f0: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
5200: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
5210: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
5220: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
5230: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
5240: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
5250: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
5260: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
5270: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
5280: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
5290: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
52a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
52b0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
52c0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
52d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
52e0: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
52f0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
5300: 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64  not close the [d
5310: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
5320: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
5330: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
5340: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
5350: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
5360: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
5370: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
5380: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
5390: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
53a0: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
53b0: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
53c0: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
53d0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
53e0: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
53f0: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
5400: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
5410: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
5420: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
5430: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
5440: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
5450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5460: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
5470: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
5480: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
5490: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
54a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
54b0: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
54c0: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
54d0: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
54e0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
54f0: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
5500: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
5510: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
5520: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5530: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
5540: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
5550: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
5560: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
5570: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5580: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
5590: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
55a0: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
55b0: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
55c0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
55d0: 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72  S: SQLITE_OK {er
55e0: 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72  ror code} {error
55f0: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
5600: 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64  RDS: {result cod
5610: 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73  e} {result codes
5620: 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c  }.**.** Many SQL
5630: 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ite functions re
5640: 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20  turn an integer 
5650: 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d  result code from
5660: 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a   the set shown.*
5670: 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20  * here in order 
5680: 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63 63  to indicate succ
5690: 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a  ess or failure..
56a0: 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20  **.** New error 
56b0: 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64  codes may be add
56c0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
56d0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
56e0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
56f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
5700: 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
5710: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a  esult codes],.**
5720: 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
5730: 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53  n_conflict()] [S
5740: 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c  QLITE_ROLLBACK |
5750: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a   result codes]..
5760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5770: 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30  E_OK           0
5780: 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c     /* Successful
5790: 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65   result */./* be
57a0: 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72  ginning-of-error
57b0: 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e  -codes */.#defin
57c0: 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20  e SQLITE_ERROR  
57d0: 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c        1   /* SQL
57e0: 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e   error or missin
57f0: 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  g database */.#d
5800: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
5810: 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a  ERNAL     2   /*
5820: 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20   Internal logic 
5830: 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20  error in SQLite 
5840: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5850: 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33  E_PERM         3
5860: 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72     /* Access per
5870: 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a  mission denied *
5880: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5890: 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20  _ABORT        4 
58a0: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f    /* Callback ro
58b0: 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20  utine requested 
58c0: 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66  an abort */.#def
58d0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  ine SQLITE_BUSY 
58e0: 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54          5   /* T
58f0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
5900: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
5910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5920: 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a  KED       6   /*
5930: 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20   A table in the 
5940: 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b  database is lock
5950: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
5960: 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20  LITE_NOMEM      
5970: 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f    7   /* A mallo
5980: 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64  c() failed */.#d
5990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
59a0: 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a  DONLY     8   /*
59b0: 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74   Attempt to writ
59c0: 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74  e a readonly dat
59d0: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
59e0: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50   SQLITE_INTERRUP
59f0: 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72  T    9   /* Oper
5a00: 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64  ation terminated
5a10: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   by sqlite3_inte
5a20: 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e  rrupt()*/.#defin
5a30: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20  e SQLITE_IOERR  
5a40: 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d       10   /* Som
5a50: 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49  e kind of disk I
5a60: 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65  /O error occurre
5a70: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
5a80: 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20  ITE_CORRUPT     
5a90: 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  11   /* The data
5aa0: 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20  base disk image 
5ab0: 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a  is malformed */.
5ac0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5ad0: 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20  OTFOUND    12   
5ae0: 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64  /* Unknown opcod
5af0: 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c  e in sqlite3_fil
5b00: 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23  e_control() */.#
5b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
5b20: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f  LL        13   /
5b30: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  * Insertion fail
5b40: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62  ed because datab
5b50: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23  ase is full */.#
5b60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5b70: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f  NTOPEN    14   /
5b80: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e  * Unable to open
5b90: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
5ba0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
5bb0: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20  LITE_PROTOCOL   
5bc0: 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   15   /* Databas
5bd0: 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20  e lock protocol 
5be0: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
5bf0: 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20   SQLITE_EMPTY   
5c00: 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61      16   /* Data
5c10: 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f  base is empty */
5c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c30: 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20  SCHEMA      17  
5c40: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
5c50: 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20   schema changed 
5c60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c70: 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38  E_TOOBIG      18
5c80: 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20     /* String or 
5c90: 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a  BLOB exceeds siz
5ca0: 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69  e limit */.#defi
5cb0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5cc0: 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62  AINT  19   /* Ab
5cd0: 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74  ort due to const
5ce0: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
5cf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d00: 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30  E_MISMATCH    20
5d10: 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20     /* Data type 
5d20: 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66  mismatch */.#def
5d30: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ine SQLITE_MISUS
5d40: 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c  E      21   /* L
5d50: 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f  ibrary used inco
5d60: 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69  rrectly */.#defi
5d70: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20  ne SQLITE_NOLFS 
5d80: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73        22   /* Us
5d90: 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e  es OS features n
5da0: 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20  ot supported on 
5db0: 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  host */.#define 
5dc0: 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20  SQLITE_AUTH     
5dd0: 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f     23   /* Autho
5de0: 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20  rization denied 
5df0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e00: 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34  E_FORMAT      24
5e10: 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20     /* Auxiliary 
5e20: 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20  database format 
5e30: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
5e40: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
5e50: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
5e60: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
5e70: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
5e80: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
5e90: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
5ea0: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
5eb0: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
5ec0: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
5ed0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
5ee0: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20  SQLITE_NOTICE   
5ef0: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66     27   /* Notif
5f00: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71  ications from sq
5f10: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
5f20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
5f30: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f  RNING     28   /
5f40: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20  * Warnings from 
5f50: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
5f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f70: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
5f80: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
5f90: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
5fa0: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
5fb0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
5fc0: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
5fd0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
5fe0: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
5ff0: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
6000: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
6010: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6020: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
6030: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
6040: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65  RDS: {extended e
6050: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65  rror code} {exte
6060: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
6070: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
6080: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
6090: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
60a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a  result codes}.**
60b0: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
60c0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
60d0: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
60e0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
60f0: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a   of 26 integer.*
6100: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72  * [SQLITE_OK | r
6110: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
6120: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
6130: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
6140: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
6150: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
6160: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
6170: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
6180: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
6190: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
61a0: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
61b0: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
61c0: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
61d0: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
61e0: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
61f0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
6200: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
6210: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65  n 3.3.8 and late
6220: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
6230: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
6240: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
6250: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
6260: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
6270: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
6280: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78  t errors. The ex
6290: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
62a0: 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  des are enabled 
62b0: 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f  or disabled.** o
62c0: 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65  n a per database
62d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
62e0: 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  s using the.** [
62f0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
6300: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
6310: 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65   API..**.** Some
6320: 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c   of the availabl
6330: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
6340: 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74  t codes are list
6350: 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20  ed here..** One 
6360: 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e  may expect the n
6370: 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65  umber of extende
6380: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77  d result codes w
6390: 69 6c 6c 20 69 6e 63 72 65 61 73 65 0a 2a 2a 20  ill increase.** 
63a0: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74  over time.  Soft
63b0: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65  ware that uses e
63c0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
63d0: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65  odes should expe
63e0: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77  ct.** to see new
63f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e   result codes in
6400: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
6410: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
6420: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
6430: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
6440: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
6450: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
6460: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
6470: 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69  y zero..*/.#defi
6480: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
6490: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
64a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
64b0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
64c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
64d0: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
64e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
64f0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
6500: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
6510: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
6520: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
6530: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
6540: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
6550: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
6560: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
6570: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
6580: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
6590: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
65a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
65b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
65c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
65d0: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
65e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
65f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6600: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
6610: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
6620: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
6630: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
6640: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
6650: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
6660: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
6670: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
6680: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
6690: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
66a0: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
66b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
66c0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
66d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
66e0: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
66f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6700: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
6710: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6720: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
6730: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6740: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
6750: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6760: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
6770: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6780: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
6790: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
67a0: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
67b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
67c0: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
67d0: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
67e0: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
67f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6800: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
6810: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6820: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
6830: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6840: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
6850: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6860: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
6870: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6880: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
6890: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
68a0: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
68b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
68c0: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
68d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
68e0: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
68f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6900: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
6910: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6920: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
6930: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6940: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
6950: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6960: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
6970: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6980: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
6990: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
69a0: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
69b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
69c0: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
69d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
69e0: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
69f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6a00: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f  _IOERR_DELETE_NO
6a10: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45  ENT      (SQLITE
6a20: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29  _IOERR | (23<<8)
6a30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6a40: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20  _IOERR_MMAP     
6a50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6a60: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29  _IOERR | (24<<8)
6a70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6a80: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41  _IOERR_GETTEMPPA
6a90: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
6aa0: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29  _IOERR | (25<<8)
6ab0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6ac0: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20  _IOERR_CONVPATH 
6ad0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6ae0: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29  _IOERR | (26<<8)
6af0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6b00: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
6b10: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
6b20: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
6b30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
6b40: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
6b50: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
6b60: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
6b70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
6b80: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
6b90: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
6ba0: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
6bb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6bc0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
6bd0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
6be0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
6bf0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
6c00: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
6c10: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
6c20: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
6c30: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
6c40: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
6c50: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
6c60: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
6c70: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
6c80: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
6c90: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
6ca0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
6cb0: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
6cc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
6cd0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
6ce0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
6cf0: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
6d00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
6d10: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
6d20: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
6d30: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
6d40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
6d50: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
6d60: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
6d70: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
6d80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6d90: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
6da0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
6db0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
6dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
6dd0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
6de0: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
6df0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
6e00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6e10: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
6e20: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
6e30: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
6e40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6e50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
6e60: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
6e70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
6e80: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
6e90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6ea0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
6eb0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6ec0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
6ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6ee0: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
6ef0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
6f00: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
6f10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6f20: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
6f30: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
6f40: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
6f50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6f60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
6f70: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
6f80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
6f90: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
6fa0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6fb0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
6fc0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6fd0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
6fe0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6ff0: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
7000: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
7010: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
7020: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7030: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
7040: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
7050: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
7060: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7070: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
7080: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
7090: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
70a0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
70b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
70c0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
70d0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
70e0: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
70f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
7100: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
7110: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
7120: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
7130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
7140: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
7150: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
7160: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
7170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
7180: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
7190: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
71a0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f  ING | (1<<8))../
71b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
71c0: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
71d0: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
71e0: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
71f0: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
7200: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
7210: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
7220: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
7230: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
7240: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
7250: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
7260: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
7270: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
7280: 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  thod..*/.#define
7290: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
72a0: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
72b0: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
72c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
72d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
72e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
72f0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
7300: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
7310: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
7320: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
7330: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
7340: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
7350: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
7360: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
7370: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
7380: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
7390: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
73a0: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
73b0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
73c0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
73d0: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
73e0: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
73f0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
7400: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
7410: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
7420: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
7430: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
7440: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
7450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
7460: 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20  00000040  /* Ok 
7470: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
7480: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
7490: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d   SQLITE_OPEN_MEM
74a0: 4f 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78  ORY           0x
74b0: 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20  00000080  /* Ok 
74c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
74d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
74e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
74f0: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
7500: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
7510: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
7520: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
7530: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
7540: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
7550: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
7560: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
7570: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
7580: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
7590: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
75a0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
75b0: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
75c0: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
75d0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
75e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
75f0: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
7600: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
7610: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
7620: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
7630: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
7640: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
7650: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
7660: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
7670: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
7680: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
7690: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
76a0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
76b0: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
76c0: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
76d0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
76e0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
76f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
7700: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
7710: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
7720: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
7730: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
7740: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
7750: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
7760: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
7770: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
7780: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
7790: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
77a0: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
77b0: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
77c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
77d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
77e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
77f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
7800: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
7810: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
7820: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
7830: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7840: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
7850: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
7860: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
7870: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
7880: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
7890: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
78a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
78b0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
78c0: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
78d0: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
78e0: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65   vector of these
78f0: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
7900: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
7910: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
7920: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
7930: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
7940: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
7950: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
7960: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
7970: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
7980: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
7990: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
79a0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
79b0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
79c0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
79d0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
79e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
79f0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
7a00: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
7a10: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
7a20: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
7a30: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
7a40: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
7a50: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
7a60: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
7a70: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
7a80: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
7a90: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7aa0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
7ab0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
7ac0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
7ad0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
7ae0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
7af0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
7b00: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
7b10: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
7b20: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
7b30: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
7b40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
7b50: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
7b60: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
7b70: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
7b80: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
7b90: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
7ba0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
7bb0: 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51  Write().  The SQ
7bc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
7bd0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70  SAFE_OVERWRITE p
7be0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
7bf0: 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f  at.** after rebo
7c00: 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ot following a c
7c10: 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f  rash or power lo
7c20: 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74  ss, the only byt
7c30: 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20  es in a.** file 
7c40: 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65  that were writte
7c50: 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  n at the applica
7c60: 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74  tion level might
7c70: 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a   have changed.**
7c80: 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65   and that adjace
7c90: 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62  nt bytes, even b
7ca0: 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  ytes within the 
7cb0: 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a  same sector are.
7cc0: 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ** guaranteed to
7cd0: 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20   be unchanged.  
7ce0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7cf0: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
7d00: 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69  N_OPEN.** flag i
7d10: 6e 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66  ndicate that a f
7d20: 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65  ile cannot be de
7d30: 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e  leted when open.
7d40: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
7d50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
7d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
7d70: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
7d80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7d90: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
7da0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
7db0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7dc0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
7dd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
7de0: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
7df0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7e00: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
7e10: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
7e20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7e30: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
7e40: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7e50: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
7e60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7e70: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
7e80: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
7e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7ea0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
7eb0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7ec0: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
7ed0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ee0: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
7ef0: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
7f00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7f10: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
7f20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
7f30: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
7f40: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
7f50: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
7f60: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
7f70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7f80: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
7f90: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
7fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7fb0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
7fc0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
7fd0: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
7fe0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
7ff0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
8000: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a      0x00001000..
8010: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8020: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
8030: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
8040: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
8050: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
8060: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
8070: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
8080: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
8090: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
80a0: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
80b0: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
80c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
80d0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
80e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
80f0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
8100: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
8110: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
8120: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
8130: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
8140: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
8150: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8160: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
8170: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
8180: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
8190: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
81a0: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
81b0: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
81c0: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
81d0: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
81e0: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
81f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
8200: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
8210: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
8220: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
8230: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
8240: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
8250: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
8260: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
8270: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
8280: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
8290: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
82a0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
82b0: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
82c0: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
82d0: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
82e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
82f0: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
8300: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
8310: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
8320: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
8330: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
8340: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
8350: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
8360: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
8370: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
8380: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
8390: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
83a0: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
83b0: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
83c0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
83d0: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
83e0: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
83f0: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
8400: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
8410: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
8420: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
8430: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
8440: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
8450: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
8460: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
8470: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
8480: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
8490: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
84a0: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
84b0: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
84c0: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
84d0: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
84e0: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
84f0: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
8500: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
8510: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
8520: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
8530: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
8540: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
8550: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
8560: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
8570: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
8580: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
8590: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
85a0: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
85b0: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
85c0: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
85d0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
85e0: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
85f0: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
8600: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
8610: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
8620: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
8630: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
8640: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
8650: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
8660: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
8670: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
8680: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
8690: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
86a0: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
86b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
86c0: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
86d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
86e0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
86f0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
8700: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
8710: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
8720: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
8730: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
8740: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
8750: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
8760: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
8770: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
8780: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
8790: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
87a0: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
87b0: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
87c0: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
87d0: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
87e0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
87f0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
8800: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
8810: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
8820: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
8830: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
8840: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
8850: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
8860: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
8870: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
8880: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
8890: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
88a0: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
88b0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
88c0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
88d0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
88e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
88f0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
8900: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
8910: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
8920: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8930: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
8940: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
8950: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
8960: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
8970: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
8980: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
8990: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
89a0: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
89b0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
89c0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
89d0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
89e0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
89f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
8a00: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
8a10: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
8a20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
8a30: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
8a40: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
8a50: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
8a60: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
8a70: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
8a80: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
8a90: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
8aa0: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
8ab0: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
8ac0: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
8ad0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
8ae0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
8af0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
8b00: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
8b10: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
8b20: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
8b30: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
8b40: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
8b50: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
8b60: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
8b70: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
8b80: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
8b90: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
8ba0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
8bb0: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
8bc0: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
8bd0: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
8be0: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
8bf0: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
8c00: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
8c10: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
8c20: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
8c30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
8c40: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
8c50: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
8c60: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
8c70: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
8c80: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
8c90: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
8ca0: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
8cb0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
8cc0: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
8cd0: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
8ce0: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
8cf0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
8d00: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
8d10: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
8d20: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
8d30: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
8d40: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
8d50: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
8d60: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
8d70: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
8d80: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
8d90: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
8da0: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
8db0: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
8dc0: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
8dd0: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
8de0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
8df0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
8e00: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8e10: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
8e20: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
8e30: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
8e40: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
8e50: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
8e60: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
8e70: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
8e80: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
8e90: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
8ea0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
8eb0: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
8ec0: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
8ed0: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
8ee0: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
8ef0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
8f00: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
8f10: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
8f20: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
8f30: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
8f40: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
8f50: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
8f60: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
8f70: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
8f80: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
8f90: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
8fa0: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
8fb0: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
8fc0: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
8fd0: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
8fe0: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
8ff0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
9000: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
9010: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
9020: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
9030: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
9040: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
9050: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
9060: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
9070: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
9080: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
9090: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
90a0: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
90b0: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
90c0: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
90d0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
90e0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
90f0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
9100: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
9110: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
9120: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
9130: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
9140: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
9150: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
9160: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
9170: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
9180: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
9190: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
91a0: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
91b0: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
91c0: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
91d0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
91e0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
91f0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
9200: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
9210: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
9220: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
9230: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
9240: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
9250: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
9260: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
9270: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
9280: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
9290: 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45  se..** A [SQLITE
92a0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
92b0: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
92c0: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
92d0: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
92e0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
92f0: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
9300: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
9310: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
9320: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
9330: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
9340: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
9350: 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65  ts.  VFS impleme
9360: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a  ntations should.
9370: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
9380: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20  E_NOTFOUND] for 
9390: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
93a0: 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64  odes that they d
93b0: 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69  o not.** recogni
93c0: 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ze..**.** The xS
93d0: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
93e0: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
93f0: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
9400: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
9410: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
9420: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
9430: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
9440: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
9450: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
9460: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
9470: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
9480: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
9490: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
94a0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
94b0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
94c0: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
94d0: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
94e0: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
94f0: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
9500: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
9510: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
9520: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
9530: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
9540: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
9550: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
9560: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
9570: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
9580: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
9590: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
95a0: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
95b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
95c0: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
95d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
95e0: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
95f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
9600: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
9610: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
9620: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
9630: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
9640: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
9650: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
9660: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
9670: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
9680: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
9690: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
96a0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
96b0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
96c0: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
96d0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
96e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
96f0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
9700: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
9710: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
9720: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
9730: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
9740: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
9750: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
9760: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
9770: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
9780: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
9790: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
97a0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
97b0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
97c0: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
97d0: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
97e0: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
97f0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
9800: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
9810: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
9820: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
9830: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
9840: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
9850: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
9860: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
9870: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
9880: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
9890: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
98a0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
98b0: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
98c0: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
98d0: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
98e0: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
98f0: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
9900: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
9910: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
9920: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
9930: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
9940: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
9950: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
9960: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
9970: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
9980: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
9990: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
99a0: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
99b0: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
99c0: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
99d0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
99e0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
99f0: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
9a00: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
9a10: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
9a20: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
9a30: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
9a40: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
9a50: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
9a60: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
9a70: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
9a80: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
9a90: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
9aa0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
9ab0: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
9ac0: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
9ad0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
9ae0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
9af0: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
9b00: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
9b10: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
9b20: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
9b30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
9b40: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
9b50: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
9b60: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
9b70: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
9b80: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
9b90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
9ba0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
9bb0: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
9bc0: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
9bd0: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
9be0: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
9bf0: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
9c00: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
9c10: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
9c20: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
9c30: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
9c40: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
9c50: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
9c60: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
9c70: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
9c80: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
9c90: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
9ca0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
9cb0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
9cc0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
9cd0: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
9ce0: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
9cf0: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
9d00: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
9d10: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
9d20: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
9d30: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
9d40: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
9d50: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
9d60: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
9d70: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
9d80: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
9d90: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
9da0: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
9db0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
9dc0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
9dd0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63  */.  int (*xFetc
9de0: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
9df0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
9e00: 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c  iOfst, int iAmt,
9e10: 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69   void **pp);.  i
9e20: 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73  nt (*xUnfetch)(s
9e30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
9e40: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
9e50: 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f  t, void *p);.  /
9e60: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
9e70: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
9e80: 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20  rsion 3 */.  /* 
9e90: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
9ea0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
9eb0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
9ec0: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
9ed0: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
9ee0: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
9ef0: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
9f00: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
9f10: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
9f20: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
9f30: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
9f40: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
9f50: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
9f60: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
9f70: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9f80: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
9f90: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
9fa0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
9fb0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
9fc0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
9fd0: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
9fe0: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
9ff0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
a000: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
a010: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
a020: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
a030: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
a040: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
a050: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
a060: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
a070: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
a080: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
a090: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
a0a0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
a0b0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
a0c0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
a0d0: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
a0e0: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
a0f0: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
a100: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
a110: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
a120: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
a130: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
a140: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
a150: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
a160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
a170: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
a180: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
a190: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
a1a0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
a1b0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
a1c0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
a1d0: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
a1e0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a1f0: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
a200: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
a210: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
a220: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
a230: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
a240: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
a250: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
a260: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
a270: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
a280: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
a290: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
a2a0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
a2b0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
a2c0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
a2d0: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
a2e0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
a2f0: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
a300: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a310: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
a320: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
a330: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
a340: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
a350: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
a360: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
a370: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
a380: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
a390: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
a3a0: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
a3b0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
a3c0: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
a3d0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
a3e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a3f0: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
a400: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
a410: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
a420: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
a430: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
a440: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
a450: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
a460: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
a470: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
a480: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
a490: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
a4a0: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
a4b0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
a4c0: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
a4d0: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
a4e0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
a4f0: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
a500: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a510: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
a520: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
a530: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
a540: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
a550: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
a560: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
a570: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
a580: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
a590: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
a5a0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
a5b0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
a5c0: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
a5d0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a5e0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
a5f0: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
a600: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
a610: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a620: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
a630: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
a640: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
a650: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a660: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
a670: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a680: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
a690: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
a6a0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
a6b0: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
a6c0: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
a6d0: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
a6e0: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
a6f0: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
a700: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
a710: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
a720: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
a730: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
a740: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
a750: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
a760: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
a770: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
a780: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
a790: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
a7a0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
a7b0: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
a7c0: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
a7d0: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
a7e0: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
a7f0: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
a800: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
a810: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
a820: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
a830: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
a840: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
a850: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
a860: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
a870: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
a880: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
a890: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
a8a0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
a8b0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
a8c0: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
a8d0: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
a8e0: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
a8f0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
a900: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
a910: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
a920: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
a930: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
a940: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
a950: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a960: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
a970: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
a980: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
a990: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
a9a0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
a9b0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
a9c0: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
a9d0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a9e0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
a9f0: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
aa00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
aa10: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
aa20: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
aa30: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
aa40: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
aa50: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
aa60: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
aa70: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
aa80: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
aa90: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
aaa0: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
aab0: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
aac0: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
aad0: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
aae0: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
aaf0: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
ab00: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
ab10: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
ab20: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
ab30: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
ab40: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
ab50: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
ab60: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
ab70: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
ab80: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
ab90: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
aba0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
abb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
abc0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
abd0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
abe0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
abf0: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
ac00: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
ac10: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
ac20: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
ac30: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
ac40: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
ac50: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
ac60: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
ac70: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
ac80: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
ac90: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
aca0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
acb0: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
acc0: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
acd0: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
ace0: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
acf0: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
ad00: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
ad10: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
ad20: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
ad30: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
ad40: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
ad50: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
ad60: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
ad70: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
ad80: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
ad90: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
ada0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
adb0: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
adc0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
add0: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
ade0: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
adf0: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
ae00: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
ae10: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
ae20: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
ae30: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
ae40: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
ae50: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
ae60: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
ae70: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
ae80: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
ae90: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
aea0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
aeb0: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
aec0: 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65  integer i the ne
aed0: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e  w retry count an
aee0: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  d the second.** 
aef0: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64  integer is the d
af00: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72  elay.  If either
af10: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61   integer is nega
af20: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73  tive, then the s
af30: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74  etting.** is not
af40: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73   changed but ins
af50: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76  tead the prior v
af60: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74  alue of that set
af70: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a  ting is written.
af80: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61  ** into the arra
af90: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e  y entry, allowin
afa0: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  g the current re
afb0: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20  try settings to 
afc0: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74  be.** interrogat
afd0: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65  ed.  The zDbName
afe0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67   parameter is ig
aff0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  nored..**.** <li
b000: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b010: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a  PERSIST_WAL]].**
b020: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
b030: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
b040: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
b050: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
b060: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
b070: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41  t [WAL | Write A
b080: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e  head Log] settin
b090: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  g.  By default, 
b0a0: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a  the auxiliary.**
b0b0: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67   write ahead log
b0c0: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
b0d0: 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f  ry files used fo
b0e0: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  r transaction co
b0f0: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74  ntrol.** are aut
b100: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
b110: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65  ed when the late
b120: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  st connection to
b130: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
b140: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e   closes.  Settin
b150: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  g persistent WAL
b160: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f   mode causes tho
b170: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73  se files to pers
b180: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f  ist after.** clo
b190: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20  se.  Persisting 
b1a0: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65  the files is use
b1b0: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70  ful when other p
b1c0: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f  rocesses that do
b1d0: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69   not.** have wri
b1e0: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e  te permission on
b1f0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63   the directory c
b200: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
b210: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74  tabase file want
b220: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20  .** to read the 
b230: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61  database file, a
b240: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68  s the WAL and sh
b250: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
b260: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20  s must exist.** 
b270: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65  in order for the
b280: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   database to be 
b290: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
b2a0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
b2b0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
b2c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
b2d0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
b2e0: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
b2f0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
b300: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
b310: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
b320: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  e persistent WAL
b330: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
b340: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a  able persistent.
b350: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66  ** WAL mode.  If
b360: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
b370: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
b380: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
b390: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57  the current.** W
b3a0: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73  AL persistence s
b3b0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
b3c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b3d0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
b3e0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
b3f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
b400: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
b410: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
b420: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
b430: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
b440: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76  nt "powersafe-ov
b450: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f  erwrite" or "PSO
b460: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65  W" setting.  The
b470: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a   PSOW setting.**
b480: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
b490: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
b4a0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
b4b0: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a  E] bit of the.**
b4c0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
b4d0: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e  ristics methods.
b4e0: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
b4f0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
b500: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
b510: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
b520: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
b530: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
b540: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
b550: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
b560: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d  disable zero-dam
b570: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  age mode or 1 to
b580: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d   enable zero-dam
b590: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66  age.** mode.  If
b5a0: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
b5b0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
b5c0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
b5d0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a  the current.** z
b5e0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
b5f0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
b600: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b610: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  L_OVERWRITE]].**
b620: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
b630: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  NTL_OVERWRITE] o
b640: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64  pcode is invoked
b650: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72   by SQLite after
b660: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72   opening.** a wr
b670: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
b680: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
b690: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72  , unless it is r
b6a0: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73  olled back for s
b6b0: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74  ome.** reason, t
b6c0: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61  he entire databa
b6d0: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  se file will be 
b6e0: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
b6f0: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74  he current .** t
b700: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73  ransaction. This
b710: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55   is used by VACU
b720: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  UM operations..*
b730: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b740: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
b750: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
b760: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
b770: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
b780: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
b790: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c  e names of.** al
b7a0: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65  l [VFSes] in the
b7b0: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65   VFS stack.  The
b7c0: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c   names are of al
b7d0: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20  l VFS shims and 
b7e0: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74  the.** final bot
b7f0: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72  tom-level VFS ar
b800: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
b810: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
b820: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
b830: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74  _malloc()] and t
b840: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f  he result is sto
b850: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a  red in the char*
b860: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61   variable.** tha
b870: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  t the fourth par
b880: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
b890: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
b8a0: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a  )] points to..**
b8b0: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72   The caller is r
b8c0: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
b8d0: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
b8e0: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73  y when done.  As
b8f0: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c   with.** all fil
b900: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e  e-control action
b910: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67  s, there is no g
b920: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
b930: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79  is will actually
b940: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e  .** do anything.
b950: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64    Callers should
b960: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
b970: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74  char* variable t
b980: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  o a NULL.** poin
b990: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73  ter in case this
b9a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
b9b0: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
b9c0: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e  .  This file-con
b9d0: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e  trol.** is inten
b9e0: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74  ded for diagnost
b9f0: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a  ic use only..**.
ba00: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ba10: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
ba20: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
ba30: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
ba40: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
ba50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ba60: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
ba70: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
ba80: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
ba90: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
baa0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
bab0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
bac0: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
bad0: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
bae0: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
baf0: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
bb00: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
bb10: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
bb20: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
bb30: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
bb40: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
bb50: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
bb60: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
bb70: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
bb80: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
bb90: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
bba0: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
bbb0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
bbc0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
bbd0: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
bbe0: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
bbf0: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
bc00: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
bc10: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
bc20: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
bc30: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
bc40: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
bc50: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
bc60: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
bc70: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
bc80: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
bc90: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
bca0: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
bcb0: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
bcc0: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
bcd0: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
bce0: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
bcf0: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
bd00: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
bd10: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
bd20: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
bd30: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
bd40: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
bd50: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
bd60: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
bd70: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
bd80: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
bd90: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
bda0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
bdb0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
bdc0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
bdd0: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
bde0: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
bdf0: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
be00: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
be10: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
be20: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
be30: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
be40: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
be50: 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74  tatement.  ^If t
be60: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
be70: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
be80: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
be90: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
bea0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
beb0: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
bec0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
bed0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
bee0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
bef0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
bf00: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
bf10: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
bf20: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
bf30: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
bf40: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
bf50: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
bf60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
bf70: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
bf80: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
bf90: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
bfa0: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
bfb0: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
bfc0: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
bfd0: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
bfe0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
bff0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
c000: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
c010: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
c020: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c030: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
c040: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
c050: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
c060: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
c070: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
c080: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
c090: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
c0a0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
c0b0: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
c0c0: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
c0d0: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
c0e0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
c0f0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
c100: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
c110: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
c120: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
c130: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
c140: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
c150: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
c160: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
c170: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
c180: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
c190: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
c1a0: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
c1b0: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
c1c0: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
c1d0: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
c1e0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
c1f0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
c200: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
c210: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
c220: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
c230: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
c240: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
c250: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
c260: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
c270: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
c280: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
c290: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
c2a0: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
c2b0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c2c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
c2d0: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
c2e0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
c2f0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
c300: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
c310: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
c320: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
c330: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
c340: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
c350: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
c360: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
c370: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
c380: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
c390: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
c3a0: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
c3b0: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
c3c0: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
c3d0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
c3e0: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
c3f0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
c400: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
c410: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
c420: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
c430: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
c440: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
c450: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
c460: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
c470: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
c480: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
c490: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
c4a0: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
c4b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
c4c0: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
c4d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
c4e0: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
c4f0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
c500: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
c510: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
c520: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
c530: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
c540: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
c550: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
c560: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
c570: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
c580: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
c590: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
c5a0: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
c5b0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
c5c0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
c5d0: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
c5e0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
c5f0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
c600: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
c610: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
c620: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
c630: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
c640: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
c650: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
c660: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
c670: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
c680: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
c690: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
c6a0: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
c6b0: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
c6c0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
c6d0: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
c6e0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
c6f0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
c700: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c710: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
c720: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c730: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
c740: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
c750: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
c760: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
c770: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
c780: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
c790: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
c7a0: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
c7b0: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
c7c0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
c7d0: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
c7e0: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
c7f0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
c800: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
c810: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
c820: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
c830: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
c840: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
c850: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
c860: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
c870: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
c880: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
c890: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
c8a0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
c8b0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
c8c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c8d0: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
c8e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c8f0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
c900: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
c910: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
c920: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
c930: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
c940: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
c950: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
c960: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
c970: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
c980: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
c990: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
c9a0: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
c9b0: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
c9c0: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
c9d0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ed..**.** </ul>.
c9e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c9f0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
ca00: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
ca10: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
ca20: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
ca30: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32  LE             2
ca40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ca50: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
ca60: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a  E             3.
ca70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
ca80: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
ca90: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
caa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cab0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
cac0: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
cad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cae0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
caf0: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
cb00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cb10: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
cb20: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
cb30: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cb40: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
cb50: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
cb60: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cb70: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
cb80: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
cb90: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
cba0: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
cbb0: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
cbc0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
cbd0: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
cbe0: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
cbf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
cc00: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
cc10: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
cc20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
cc30: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
cc40: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
cc50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
cc60: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
cc70: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
cc80: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
cc90: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
cca0: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
ccb0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
ccc0: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
ccd0: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
cce0: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
ccf0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
cd00: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
cd10: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
cd20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
cd30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cd40: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20  FCNTL_HAS_MOVED 
cd50: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a               20.
cd60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cd70: 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20  CNTL_SYNC       
cd80: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23              21.#
cd90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cda0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
cdb0: 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 0a 2f  TWO        22../
cdc0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
cdd0: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
cde0: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
cdf0: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
ce00: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
ce10: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
ce20: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
ce30: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
ce40: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
ce50: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
ce60: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
ce70: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
ce80: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
ce90: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
cea0: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
ceb0: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
cec0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
ced0: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
cee0: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
cef0: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
cf00: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
cf10: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
cf20: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
cf30: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
cf40: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
cf50: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
cf60: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
cf70: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
cf80: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
cf90: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
cfa0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
cfb0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
cfc0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
cfd0: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
cfe0: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
cff0: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
d000: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
d010: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
d020: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
d030: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
d040: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
d050: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
d060: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
d070: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
d080: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
d090: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
d0a0: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
d0b0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
d0c0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
d0d0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
d0e0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
d0f0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
d100: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
d110: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
d120: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
d130: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
d140: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
d150: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
d160: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
d170: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
d180: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
d190: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
d1a0: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
d1b0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
d1c0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
d1d0: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
d1e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
d1f0: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
d200: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
d210: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
d220: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
d230: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
d240: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
d250: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
d260: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
d270: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
d280: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
d290: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
d2a0: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
d2b0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
d2c0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
d2d0: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
d2e0: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
d2f0: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
d300: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
d310: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
d320: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
d330: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
d340: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
d350: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
d360: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
d370: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
d380: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
d390: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
d3a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
d3b0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
d3c0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
d3d0: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
d3e0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
d3f0: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
d400: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
d410: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
d420: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
d430: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
d440: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
d450: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
d460: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
d470: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
d480: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
d490: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
d4a0: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
d4b0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
d4c0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
d4d0: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
d4e0: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
d4f0: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
d500: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
d510: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
d520: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
d530: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
d540: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
d550: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
d560: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
d570: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
d580: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
d590: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
d5a0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
d5b0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
d5c0: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
d5d0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
d5e0: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
d5f0: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
d600: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
d610: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
d620: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
d630: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
d640: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
d650: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
d660: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
d670: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d680: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
d690: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
d6a0: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
d6b0: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
d6c0: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
d6d0: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
d6e0: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
d6f0: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
d700: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
d710: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
d720: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
d730: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
d740: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
d750: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
d760: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
d770: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
d780: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
d790: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
d7a0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
d7b0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
d7c0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
d7d0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
d7e0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
d7f0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
d800: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
d810: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
d820: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
d830: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
d840: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
d850: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
d860: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
d870: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
d880: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
d890: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
d8a0: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
d8b0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
d8c0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
d8d0: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
d8e0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
d8f0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
d900: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
d910: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
d920: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
d930: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
d940: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
d950: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
d960: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
d970: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
d980: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
d990: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
d9a0: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
d9b0: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
d9c0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
d9d0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
d9e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
d9f0: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
da00: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
da10: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
da20: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
da30: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
da40: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
da50: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
da60: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
da70: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
da80: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
da90: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
daa0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
dab0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
dac0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
dad0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
dae0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
daf0: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
db00: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
db10: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
db20: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
db30: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
db40: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
db50: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
db60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
db70: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
db80: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
db90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
dba0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
dbb0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
dbc0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
dbd0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
dbe0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
dbf0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
dc00: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
dc10: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
dc20: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
dc30: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
dc40: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
dc50: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
dc60: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
dc70: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
dc80: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
dc90: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
dca0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
dcb0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
dcc0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
dcd0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
dce0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
dcf0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
dd00: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
dd10: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
dd20: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
dd30: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
dd40: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
dd50: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
dd60: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
dd70: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
dd80: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
dd90: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
dda0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
ddb0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
ddc0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
ddd0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
dde0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
ddf0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
de00: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
de10: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
de20: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
de30: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
de40: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
de50: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
de60: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
de70: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
de80: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
de90: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
dea0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
deb0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
dec0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
ded0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
dee0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
def0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
df00: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
df10: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
df20: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
df30: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
df40: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
df50: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
df60: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
df70: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
df80: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
df90: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
dfa0: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
dfb0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
dfc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
dfd0: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
dfe0: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
dff0: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
e000: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
e010: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
e020: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
e030: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
e040: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
e050: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
e060: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
e070: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
e080: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
e090: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
e0a0: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
e0b0: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
e0c0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
e0d0: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
e0e0: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
e0f0: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
e100: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
e110: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
e120: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
e130: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
e140: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
e150: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
e160: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
e170: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
e180: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
e190: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
e1a0: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
e1b0: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
e1c0: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
e1d0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
e1e0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
e1f0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
e200: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
e210: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
e220: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
e230: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
e240: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
e250: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
e260: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
e270: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
e280: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
e290: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
e2a0: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
e2b0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
e2c0: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
e2d0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
e2e0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
e2f0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
e300: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
e310: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
e320: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
e330: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
e340: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
e350: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
e360: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
e370: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
e380: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
e390: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
e3a0: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
e3b0: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
e3c0: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
e3d0: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
e3e0: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
e3f0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
e400: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
e410: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
e420: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
e430: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
e440: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
e450: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e460: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
e470: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
e480: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
e490: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
e4a0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e4b0: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
e4c0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
e4d0: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
e4e0: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
e4f0: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
e500: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
e510: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
e520: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
e530: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
e540: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
e550: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
e560: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
e570: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
e580: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
e590: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
e5a0: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
e5b0: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
e5c0: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
e5d0: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
e5e0: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
e5f0: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
e600: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
e610: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
e620: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
e630: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
e640: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
e650: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
e660: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
e670: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
e680: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
e690: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
e6a0: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
e6b0: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
e6c0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
e6d0: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
e6e0: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
e6f0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
e700: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
e710: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
e720: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
e730: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
e740: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
e750: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
e760: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
e770: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
e780: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
e790: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
e7a0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
e7b0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
e7c0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
e7d0: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
e7e0: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
e7f0: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
e800: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
e810: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
e820: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
e830: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
e840: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
e850: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
e860: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
e870: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
e880: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
e890: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
e8a0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
e8b0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
e8c0: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
e8d0: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
e8e0: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
e8f0: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
e900: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
e910: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
e920: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
e930: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
e940: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
e950: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
e960: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
e970: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
e980: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
e990: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
e9a0: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
e9b0: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
e9c0: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
e9d0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
e9e0: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
e9f0: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
ea00: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
ea10: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
ea20: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
ea30: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
ea40: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
ea50: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
ea60: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
ea70: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
ea80: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
ea90: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
eaa0: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
eab0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
eac0: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
ead0: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
eae0: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
eaf0: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
eb00: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
eb10: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
eb20: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
eb30: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
eb40: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
eb50: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
eb60: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
eb70: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
eb80: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
eb90: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
eba0: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
ebb0: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
ebc0: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
ebd0: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
ebe0: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
ebf0: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
ec00: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
ec10: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
ec20: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
ec30: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
ec40: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
ec50: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
ec60: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
ec70: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
ec80: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
ec90: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
eca0: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
ecb0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
ecc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
ecd0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
ece0: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
ecf0: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
ed00: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
ed10: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
ed20: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
ed30: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
ed40: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
ed50: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
ed60: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
ed70: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
ed80: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
ed90: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
eda0: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
edb0: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
edc0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
edd0: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
ede0: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
edf0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
ee00: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
ee10: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
ee20: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
ee30: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
ee40: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
ee50: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
ee60: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
ee70: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
ee80: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
ee90: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
eea0: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
eeb0: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
eec0: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
eed0: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
eee0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
eef0: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
ef00: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
ef10: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
ef20: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
ef30: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
ef40: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
ef50: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
ef60: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
ef70: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
ef80: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
ef90: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
efa0: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
efb0: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
efc0: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
efd0: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
efe0: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
eff0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
f000: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
f010: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
f020: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
f030: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
f040: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
f050: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f060: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f070: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
f080: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
f090: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f0a0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f0b0: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
f0c0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
f0d0: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
f0e0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
f0f0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
f100: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
f110: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
f120: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
f130: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
f140: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
f150: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
f160: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
f170: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
f180: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
f190: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
f1a0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
f1b0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
f1c0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
f1d0: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
f1e0: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
f1f0: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
f200: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
f210: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
f220: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
f230: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
f240: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
f250: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
f260: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
f270: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
f280: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
f290: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
f2a0: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
f2b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
f2c0: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
f2d0: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
f2e0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
f2f0: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
f300: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
f310: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
f320: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
f330: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
f340: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
f350: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
f360: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
f370: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
f380: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
f390: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
f3a0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
f3b0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
f3c0: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
f3d0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
f3e0: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
f3f0: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
f400: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
f410: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
f420: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
f430: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
f440: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
f450: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
f460: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
f470: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
f480: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
f490: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
f4a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
f4b0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
f4c0: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
f4d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
f4e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
f4f0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
f500: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
f510: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
f520: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
f530: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
f540: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
f550: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
f560: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
f570: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
f580: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
f590: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
f5a0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
f5b0: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
f5c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f5d0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
f5e0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
f5f0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
f600: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
f610: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
f620: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
f630: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
f640: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
f650: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
f660: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
f670: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
f680: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
f690: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
f6a0: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
f6b0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
f6c0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
f6d0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
f6e0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
f6f0: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
f700: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
f710: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
f720: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
f730: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
f740: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
f750: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
f760: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
f770: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
f780: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
f790: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
f7a0: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
f7b0: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
f7c0: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
f7d0: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
f7e0: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
f7f0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
f800: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
f810: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
f820: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
f830: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
f840: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
f850: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
f860: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
f870: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
f880: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
f890: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f8a0: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
f8b0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
f8c0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
f8d0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
f8e0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
f8f0: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
f900: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
f910: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
f920: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
f930: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
f940: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
f950: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
f960: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
f970: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
f980: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f990: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
f9a0: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
f9b0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
f9c0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
f9d0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
f9e0: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
f9f0: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
fa00: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
fa10: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
fa20: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
fa30: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
fa40: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
fa50: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
fa60: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
fa70: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
fa80: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
fa90: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
faa0: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
fab0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
fac0: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
fad0: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
fae0: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
faf0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
fb00: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
fb10: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
fb20: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
fb30: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
fb40: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
fb50: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
fb60: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
fb70: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
fb80: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
fb90: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
fba0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
fbb0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
fbc0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
fbd0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
fbe0: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
fbf0: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
fc00: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
fc10: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
fc20: 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
fc30: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
fc40: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
fc50: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
fc60: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
fc70: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
fc80: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
fc90: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
fca0: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
fcb0: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
fcc0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
fcd0: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
fce0: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
fcf0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
fd00: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
fd10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
fd20: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
fd30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
fd40: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
fd50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fd60: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
fd70: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
fd80: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
fd90: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
fda0: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
fdb0: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
fdc0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
fdd0: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
fde0: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
fdf0: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
fe00: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
fe10: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
fe20: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
fe30: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
fe40: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
fe50: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
fe60: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
fe70: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
fe80: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
fe90: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
fea0: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
feb0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
fec0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
fed0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
fee0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
fef0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
ff00: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
ff10: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
ff20: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
ff30: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
ff40: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
ff50: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
ff60: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
ff70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
ff80: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
ff90: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
ffa0: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
ffb0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
ffc0: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
ffd0: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
ffe0: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
fff0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
10000 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
10010 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
10020 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
10030 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
10040 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
10050 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
10060 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
10070 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
10080 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
10090 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
100a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
100b0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
100c0 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
100d0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
100e0 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
100f0 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
10100 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10110 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
10120 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
10130 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
10140 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
10150 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
10160 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
10170 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10180 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
10190 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
101a0 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
101b0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
101c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
101d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
101e0 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
101f0 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
10200 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
10210 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
10220 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
10230 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
10240 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10250 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
10260 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
10270 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
10280 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
10290 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
102a0 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
102b0 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
102c0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
102d0 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
102e0 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
102f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10300 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
10310 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
10320 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
10330 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
10340 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
10350 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
10360 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
10370 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
10380 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
10390 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
103a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
103b0 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
103c0 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
103d0 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
103e0 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
103f0 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
10400 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
10410 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
10420 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
10430 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
10440 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10450 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
10460 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10470 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
10480 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10490 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
104a0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
104b0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
104c0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
104d0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
104e0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
104f0 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
10500 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
10510 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
10520 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
10530 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
10540 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
10550 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
10560 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
10570 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
10580 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
10590 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
105a0 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
105b0 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
105c0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
105d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
105e0 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
105f0 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
10600 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
10610 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
10620 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
10630 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
10640 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
10650 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
10660 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
10670 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
10680 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
10690 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
106a0 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
106b0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
106c0 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
106d0 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
106e0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
106f0 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
10700 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
10710 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
10720 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
10730 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
10740 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
10750 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
10760 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
10770 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
10780 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
10790 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
107a0 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
107b0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
107c0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
107d0 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
107e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
107f0 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
10800 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10810 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
10820 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
10830 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
10840 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
10850 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
10860 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
10870 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
10880 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
10890 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
108a0 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
108b0 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
108c0 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
108d0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
108e0 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
108f0 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
10900 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
10910 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
10920 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
10930 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
10940 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
10950 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
10960 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
10970 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
10980 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
10990 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
109a0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
109b0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
109c0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
109d0 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
109e0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
109f0 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
10a00 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
10a10 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
10a20 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
10a30 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
10a40 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
10a50 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
10a60 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
10a70 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
10a80 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
10a90 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
10aa0 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
10ab0 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
10ac0 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
10ad0 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
10ae0 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
10af0 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
10b00 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
10b10 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
10b20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
10b30 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
10b40 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
10b50 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
10b60 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
10b70 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
10b80 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
10b90 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
10ba0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
10bb0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
10bc0 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
10bd0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
10be0 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
10bf0 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
10c00 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
10c10 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10c20 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
10c30 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
10c40 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
10c50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
10c60 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
10c70 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
10c80 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
10c90 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
10ca0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
10cb0 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
10cc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
10cd0 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
10ce0 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
10cf0 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
10d00 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
10d10 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
10d20 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
10d30 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
10d40 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
10d50 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
10d60 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
10d70 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
10d80 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
10d90 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
10da0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
10db0 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
10dc0 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
10dd0 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
10de0 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
10df0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10e00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
10e10 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
10e20 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
10e30 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
10e40 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
10e50 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
10e60 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
10e70 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
10e80 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
10e90 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
10ea0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
10eb0 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
10ec0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
10ed0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10ee0 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ze(void);.SQLITE
10ef0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
10f00 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
10f10 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
10f20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10f30 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
10f40 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  I int sqlite3_os
10f50 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
10f60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10f70 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
10f80 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
10f90 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
10fa0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10fb0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
10fc0 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
10fd0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
10fe0 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
10ff0 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
11000 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
11010 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
11020 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
11030 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
11040 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
11050 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
11060 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
11070 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
11080 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
11090 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
110a0 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
110b0 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
110c0 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
110d0 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
110e0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
110f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11100 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
11110 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
11120 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
11130 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
11140 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
11150 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
11160 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
11170 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
11180 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
11190 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
111a0 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
111b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
111c0 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
111d0 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
111e0 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
111f0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
11200 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11210 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
11220 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
11230 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
11240 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
11250 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
11260 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
11270 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
11280 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
11290 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
112a0 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
112b0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
112c0 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
112d0 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
112e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
112f0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
11300 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
11310 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
11320 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
11330 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
11340 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
11350 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
11360 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
11370 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
11380 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
11390 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
113a0 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
113b0 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
113c0 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
113d0 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
113e0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
113f0 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
11400 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
11410 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
11420 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
11430 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11440 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
11450 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11460 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
11470 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
11480 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
11490 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
114a0 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
114b0 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
114c0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
114d0 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
114e0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
114f0 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
11500 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53  rror code]..*/.S
11510 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
11520 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
11530 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
11540 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
11550 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
11560 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  ections.**.** Th
11570 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
11580 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
11590 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
115a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
115b0 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
115c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
115d0 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
115e0 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
115f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
11600 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
11610 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
11620 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
11630 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
11640 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
11650 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
11660 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
11670 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
11680 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
11690 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
116a0 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
116b0 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
116c0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
116d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
116e0 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
116f0 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
11700 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
11710 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
11720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11730 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
11740 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
11750 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
11760 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
11770 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
11780 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
11790 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
117a0 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
117b0 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
117c0 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
117d0 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
117e0 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
117f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
11800 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
11810 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
11820 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
11830 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
11840 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
11850 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
11860 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
11870 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
11880 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
11890 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
118a0 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
118b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
118c0 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
118d0 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
118e0 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
118f0 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
11900 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
11910 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
11920 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
11930 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
11940 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
11950 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11960 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
11970 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11980 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
11990 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
119a0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
119b0 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
119c0 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
119d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
119e0 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
119f0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
11a00 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
11a10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11a20 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
11a30 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
11a40 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
11a50 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
11a60 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
11a70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11a80 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
11a90 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
11aa0 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
11ab0 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
11ac0 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
11ad0 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
11ae0 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
11af0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
11b00 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
11b10 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
11b20 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
11b30 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
11b40 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
11b50 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
11b60 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
11b70 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
11b80 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
11b90 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
11ba0 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
11bb0 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
11bc0 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
11bd0 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
11be0 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
11bf0 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
11c00 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
11c10 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
11c20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
11c30 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
11c40 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
11c50 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
11c60 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
11c70 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
11c80 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
11c90 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
11ca0 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
11cb0 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
11cc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
11cd0 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
11ce0 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
11cf0 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
11d00 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
11d10 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
11d20 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
11d30 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
11d40 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
11d50 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
11d60 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
11d70 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
11d80 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
11d90 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
11da0 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
11db0 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
11dc0 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
11dd0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
11de0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
11df0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
11e00 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
11e10 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
11e20 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
11e30 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
11e40 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
11e50 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
11e60 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
11e70 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
11e80 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
11e90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
11ea0 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
11eb0 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
11ec0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
11ed0 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
11ee0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
11ef0 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
11f00 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
11f10 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
11f20 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
11f30 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
11f40 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
11f50 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
11f60 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
11f70 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
11f80 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
11f90 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
11fa0 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
11fb0 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
11fc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11fd0 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
11fe0 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
11ff0 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
12000 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
12010 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
12020 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
12030 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
12040 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
12050 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
12060 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
12070 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
12080 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
12090 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
120a0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
120b0 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
120c0 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
120d0 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
120e0 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
120f0 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
12100 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
12110 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
12120 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
12130 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
12140 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
12150 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12160 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
12170 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
12180 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
12190 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
121a0 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
121b0 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
121c0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
121d0 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
121e0 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
121f0 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
12200 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
12210 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
12220 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
12230 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
12240 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
12250 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
12260 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
12270 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
12280 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
12290 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
122a0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
122b0 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
122c0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
122d0 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
122e0 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
122f0 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
12300 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
12310 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
12320 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
12330 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
12340 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
12350 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
12360 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12370 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
12380 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
12390 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
123a0 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
123b0 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
123c0 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
123d0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
123e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
123f0 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
12400 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
12410 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
12420 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
12430 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
12440 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
12450 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
12460 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
12470 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
12480 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
12490 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
124a0 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
124b0 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
124c0 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
124d0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
124e0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
124f0 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
12500 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
12510 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
12520 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
12530 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
12540 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
12550 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12560 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
12570 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
12580 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
12590 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
125a0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
125b0 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
125c0 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
125d0 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
125e0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
125f0 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
12600 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
12610 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
12620 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
12630 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
12640 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
12650 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
12660 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
12670 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
12680 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
12690 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
126a0 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
126b0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
126c0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
126d0 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
126e0 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
126f0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
12700 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
12710 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
12720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
12730 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
12740 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
12750 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
12760 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
12770 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
12780 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
12790 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
127a0 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
127b0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
127c0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
127d0 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
127e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
127f0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
12800 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
12810 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
12820 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12830 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
12840 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
12850 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
12860 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
12870 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
12880 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
12890 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
128a0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
128b0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
128c0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
128d0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
128e0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
128f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
12900 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
12910 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
12920 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
12930 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
12940 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
12950 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
12960 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
12970 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
12980 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
12990 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
129a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
129b0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
129c0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
129d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
129e0 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
129f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
12a00 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
12a10 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12a20 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
12a30 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
12a40 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
12a50 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
12a60 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
12a70 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
12a80 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
12a90 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
12aa0 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
12ab0 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
12ac0 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
12ad0 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
12ae0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
12af0 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
12b00 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12b10 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12b20 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
12b30 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
12b40 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
12b50 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
12b60 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
12b70 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
12b80 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12b90 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
12ba0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
12bb0 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
12bc0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
12bd0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12be0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
12bf0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12c00 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
12c10 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
12c20 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
12c30 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
12c40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12c50 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
12c60 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12c70 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
12c80 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12c90 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12ca0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12cb0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12cc0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
12cd0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12ce0 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
12cf0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
12d00 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
12d10 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
12d20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12d30 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
12d40 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
12d50 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
12d60 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
12d70 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
12d80 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
12d90 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12da0 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
12db0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12dc0 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
12dd0 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
12de0 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
12df0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
12e00 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
12e10 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
12e20 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
12e30 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
12e40 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
12e50 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
12e60 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
12e70 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
12e80 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
12e90 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12ea0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12eb0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12ec0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12ed0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12ee0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12ef0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12f00 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
12f10 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
12f20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12f30 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
12f40 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
12f50 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12f60 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
12f70 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
12f80 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12f90 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
12fa0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12fb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12fc0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12fd0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12fe0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12ff0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
13000 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
13010 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
13020 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
13030 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
13040 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
13050 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
13060 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
13070 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
13080 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
13090 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
130a0 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
130b0 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
130c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
130d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
130e0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
130f0 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
13100 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
13110 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
13120 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13130 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
13140 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
13150 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
13160 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
13170 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
13180 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
13190 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
131a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
131b0 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
131c0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
131d0 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
131e0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
131f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
13200 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
13210 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
13220 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
13230 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
13240 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
13250 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13260 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
13270 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
13280 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
13290 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
132a0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
132b0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
132c0 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
132d0 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
132e0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
132f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13300 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
13310 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
13320 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
13330 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
13340 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
13350 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13360 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
13370 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13380 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
13390 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
133a0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
133b0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
133c0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
133d0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
133e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
133f0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
13400 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13410 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13420 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
13430 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
13440 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
13450 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
13460 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
13470 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
13480 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
13490 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
134a0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
134b0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
134c0 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
134d0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
134e0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
134f0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
13500 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
13510 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
13520 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
13530 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
13540 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
13550 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13560 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
13570 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13580 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
13590 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
135a0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
135b0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
135c0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
135d0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
135e0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
135f0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13600 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
13610 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
13620 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
13630 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
13640 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
13650 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
13660 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
13670 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
13680 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
13690 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
136a0 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
136b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
136c0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
136d0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
136e0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
136f0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
13700 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
13710 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
13720 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
13730 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13740 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
13750 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13760 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
13770 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
13780 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
13790 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
137a0 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
137b0 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
137c0 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
137d0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
137e0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
137f0 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
13800 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
13810 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
13820 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13830 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
13840 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
13850 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
13860 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
13870 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
13880 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
13890 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
138a0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
138b0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
138c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
138d0 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
138e0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
138f0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
13900 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
13910 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
13920 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
13930 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13940 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
13950 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
13960 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
13970 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
13980 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
13990 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
139a0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
139b0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
139c0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
139d0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
139e0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
139f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13a00 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
13a10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13a20 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
13a30 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
13a40 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
13a50 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
13a60 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
13a70 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
13a80 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
13a90 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
13aa0 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
13ab0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
13ac0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
13ad0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
13ae0 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
13af0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
13b00 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
13b10 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
13b20 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13b30 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
13b40 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
13b50 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
13b60 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
13b70 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
13b80 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
13b90 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
13ba0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13bb0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
13bc0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
13bd0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
13be0 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
13bf0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
13c00 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
13c10 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
13c20 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61  re than two scra
13c30 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
13c40 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
13c50 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
13c60 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65  o twice the expe
13c70 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
13c80 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a  ber of threads..
13c90 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
13ca0 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20  never require a 
13cb0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
13cc0 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
13cd0 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
13ce0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
13cf0 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  ze. ^If SQLite n
13d00 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
13d10 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
13d20 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
13d30 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
13d40 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
13d50 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
13d60 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
13d70 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
13d80 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
13d90 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
13da0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
13db0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13dc0 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
13dd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13de0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
13df0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
13e00 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
13e10 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
13e20 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
13e30 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
13e40 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
13e50 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
13e60 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
13e70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
13e80 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
13e90 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
13ea0 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
13eb0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
13ec0 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
13ed0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13ee0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
13ef0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
13f00 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69  FIG_PCACHE2 opti
13f10 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
13f20 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
13f30 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
13f40 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
13f50 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
13f60 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
13f70 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
13f80 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
13f90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
13fa0 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
13fb0 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
13fc0 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
13fd0 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
13fe0 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
13ff0 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
14000 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
14010 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
14020 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
14030 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
14040 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
14050 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
14060 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
14070 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
14080 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
14090 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
140a0 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
140b0 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
140c0 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
140d0 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
140e0 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
140f0 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
14100 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
14110 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
14120 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
14130 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
14140 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
14150 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
14160 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
14170 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
14180 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
14190 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
141a0 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
141b0 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
141c0 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
141d0 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
141e0 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
141f0 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
14200 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
14210 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
14220 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
14230 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
14240 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
14250 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
14260 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
14270 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
14280 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
14290 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
142a0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
142b0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
142c0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
142d0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
142e0 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
142f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14300 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c  _CONFIG_HEAP]] <
14310 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14320 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
14330 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
14340 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
14350 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
14360 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
14370 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
14380 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
14390 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
143a0 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
143b0 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
143c0 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
143d0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
143e0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
143f0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
14400 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
14410 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
14420 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
14430 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
14440 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
14450 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
14460 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
14470 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
14480 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
14490 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
144a0 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
144b0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
144c0 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
144d0 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
144e0 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
144f0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
14500 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
14510 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
14520 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
14530 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
14540 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
14550 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
14560 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
14570 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
14580 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
14590 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
145a0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
145b0 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
145c0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
145d0 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
145e0 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
145f0 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
14600 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
14610 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
14620 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
14630 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
14640 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
14650 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
14660 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
14670 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
14680 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
14690 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
146a0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
146b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
146c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
146d0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
146e0 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
146f0 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
14700 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
14710 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
14720 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
14730 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
14740 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
14750 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14760 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
14770 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
14780 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
14790 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
147a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
147b0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
147c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
147d0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
147e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
147f0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14800 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
14810 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
14820 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
14830 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
14840 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
14850 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
14860 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
14870 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
14880 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
14890 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
148a0 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
148b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
148c0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
148d0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
148e0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
148f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
14900 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
14910 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
14920 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
14930 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
14940 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
14950 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
14960 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
14970 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
14980 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
14990 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
149a0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
149b0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
149c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
149d0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
149e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
149f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14a00 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
14a10 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
14a20 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
14a30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
14a40 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
14a50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14a60 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
14a70 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
14a80 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14a90 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
14aa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14ab0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
14ac0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
14ad0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14ae0 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
14af0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
14b00 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
14b10 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
14b20 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
14b30 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
14b40 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
14b50 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
14b60 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
14b70 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
14b80 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
14b90 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
14ba0 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
14bb0 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
14bc0 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
14bd0 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
14be0 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
14bf0 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
14c00 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
14c10 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
14c20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14c30 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14c40 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14c50 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
14c60 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
14c70 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
14c80 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
14c90 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
14ca0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
14cb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
14cc0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
14cd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14ce0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
14cf0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
14d00 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
14d10 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
14d20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14d30 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
14d40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14d50 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
14d60 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
14d70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
14d80 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
14d90 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
14da0 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
14db0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
14dc0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
14dd0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
14de0 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
14df0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
14e00 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
14e10 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
14e20 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
14e30 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
14e40 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
14e50 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
14e60 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
14e70 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
14e80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14e90 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
14ea0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
14eb0 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
14ec0 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
14ed0 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
14ee0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
14ef0 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
14f00 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
14f10 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
14f20 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
14f30 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
14f40 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
14f50 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
14f60 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14f70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14f80 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
14f90 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14fa0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14fb0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
14fc0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14fd0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
14fe0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
14ff0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
15000 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
15010 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
15020 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74  pecifies the int
15030 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63  erface.** to a c
15040 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
15050 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
15060 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
15070 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
15080 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
15090 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
150a0 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
150b0 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
150c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
150d0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
150e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
150f0 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
15100 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
15110 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
15120 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
15130 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
15140 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
15150 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
15160 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
15170 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
15180 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
15190 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
151a0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
151b0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
151c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
151d0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
151e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
151f0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
15200 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
15210 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
15220 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
15230 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
15240 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
15250 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
15260 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15270 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
15280 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
15290 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
152a0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
152b0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
152c0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
152d0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
152e0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
152f0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
15300 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
15310 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
15320 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
15330 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
15340 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
15350 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
15360 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
15370 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
15380 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
15390 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
153a0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
153b0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
153c0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
153d0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
153e0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
153f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15400 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
15410 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
15420 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
15430 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
15440 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
15450 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
15460 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
15470 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
15480 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
15490 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
154a0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
154b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
154c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
154d0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
154e0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
154f0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
15500 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
15510 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
15520 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
15530 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
15540 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
15550 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
15560 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
15570 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
15580 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
15590 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
155a0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
155b0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
155c0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
155d0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
155e0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
155f0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
15600 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15610 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
15620 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
15630 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
15640 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
15650 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
15660 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
15670 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
15680 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
15690 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
156a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
156b0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
156c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
156d0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20  I.** <dd>^(This 
156e0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
156f0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
15700 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e  f type int. If n
15710 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a  on-zero, then.**
15720 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
15730 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
15740 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
15750 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  ter is zero, the
15760 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a  n URI handling.*
15770 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  * is globally di
15780 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
15790 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
157a0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
157b0 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
157c0 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
157d0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
157e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
157f0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
15800 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
15810 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
15820 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
15830 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
15840 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
15850 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
15860 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
15870 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
15880 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
15890 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
158a0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
158b0 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
158c0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
158d0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
158e0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
158f0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
15900 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
15910 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
15920 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
15930 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15940 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
15950 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
15960 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
15970 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
15980 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
15990 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
159a0 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
159b0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
159c0 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
159d0 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
159e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
159f0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
15a00 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
15a10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15a20 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
15a30 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74  ** <dd>^This opt
15a40 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15a50 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d  le integer argum
15a60 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
15a70 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61  erpreted as.** a
15a80 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65   boolean in orde
15a90 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  r to enable or d
15aa0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
15ab0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
15ac0 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74  es for.** full t
15ad0 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68  able scans in th
15ae0 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
15af0 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  r.  ^The default
15b00 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65   setting is dete
15b10 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65  rmined.** by the
15b20 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43   [SQLITE_ALLOW_C
15b30 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
15b40 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  AN] compile-time
15b50 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22   option, or is "
15b60 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63  on".** if that c
15b70 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15b80 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  on is omitted..*
15b90 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f  * The ability to
15ba0 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
15bb0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
15bc0 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
15bd0 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20  ble scans.** is 
15be0 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63  because some inc
15bf0 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c  orrectly coded l
15c00 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f  egacy applicatio
15c10 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63  ns might malfunc
15c20 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65  tion.** when the
15c30 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73   optimization is
15c40 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69   enabled.  Provi
15c50 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79  ding the ability
15c60 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74   to.** disable t
15c70 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
15c80 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72  allows the older
15c90 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74  , buggy applicat
15ca0 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  ion code to work
15cb0 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e  .** without chan
15cc0 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77  ge even with new
15cd0 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
15ce0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  QLite..**.** [[S
15cf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15d00 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
15d10 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
15d20 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15d30 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
15d40 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
15d50 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
15d60 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
15d70 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
15d80 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
15d90 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
15da0 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
15db0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
15dc0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
15dd0 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
15de0 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  -ops..** </dd>.*
15df0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15e00 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a  NFIG_SQLLOG]].**
15e10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15e20 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64  IG_SQLLOG.** <dd
15e30 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  >This option is 
15e40 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
15e50 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70  f sqlite is comp
15e60 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
15e70 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
15e80 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63  SQLLOG] pre-proc
15e90 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
15ea0 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ned. The first a
15eb0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a  rgument should.*
15ec0 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  * be a pointer t
15ed0 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
15ee0 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69  type void(*)(voi
15ef0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73  d*,sqlite3*,cons
15f00 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a  t char*, int)..*
15f10 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f  * The second sho
15f20 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28  uld be of type (
15f30 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c  void*). The call
15f40 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
15f50 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a  by the library.*
15f60 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72  * in three separ
15f70 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ate circumstance
15f80 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  s, identified by
15f90 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
15fa0 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  d as the.** four
15fb0 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  th parameter. If
15fc0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
15fd0 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e  meter is 0, then
15fe0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
15ff0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73  nnection.** pass
16000 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
16010 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75   argument has ju
16020 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  st been opened. 
16030 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
16040 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  nt.** points to 
16050 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e  a buffer contain
16060 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
16070 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
16080 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a  e file. If the.*
16090 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
160a0 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68  er is 1, then th
160b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
160c0 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70  that the third p
160d0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e  arameter.** poin
160e0 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62  ts to has just b
160f0 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72  een executed. Or
16100 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20  , if the fourth 
16110 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20  parameter is 2, 
16120 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e  then.** the conn
16130 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73  ection being pas
16140 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
16150 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62  d parameter is b
16160 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65  eing closed. The
16170 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
16180 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55  ter is passed NU
16190 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e  LL In this case.
161a0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20    An example of 
161b0 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f  using this.** co
161c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
161d0 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69  on can be seen i
161e0 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c  n the "test_sqll
161f0 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c  og.c" source fil
16200 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f  e in.** the cano
16210 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75  nical SQLite sou
16220 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a  rce tree.</dd>.*
16230 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16240 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  NFIG_MMAP_SIZE]]
16250 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16260 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a  ONFIG_MMAP_SIZE.
16270 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43  ** <dd>^SQLITE_C
16280 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
16290 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74  takes two 64-bit
162a0 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65   integer (sqlite
162b0 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a  3_int64) values.
162c0 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20  ** that are the 
162d0 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a  default mmap siz
162e0 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66  e limit (the def
162f0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72  ault setting for
16300 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  .** [PRAGMA mmap
16310 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20  _size]) and the 
16320 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
16330 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e  mmap size limit.
16340 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
16350 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20   setting can be 
16360 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61  overridden by ea
16370 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
16380 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  ection using.** 
16390 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47  either the [PRAG
163a0 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f  MA mmap_size] co
163b0 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69  mmand, or by usi
163c0 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
163d0 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
163e0 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e  E] file control.
163f0 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20    ^(The maximum 
16400 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
16410 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63  e.** cannot be c
16420 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69  hanged at run-ti
16430 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65  me.  Nor may the
16440 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
16450 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78   mmap size.** ex
16460 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65  ceed the compile
16470 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
16480 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
16490 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
164a0 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
164b0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
164c0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
164d0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
164e0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
164f0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
16500 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
16510 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
16520 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
16530 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
16540 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
16550 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
16560 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16570 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
16580 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74  ** <dd>^This opt
16590 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
165a0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
165b0 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
165c0 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68 20  Windows.** with 
165d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
165e0 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
165f0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65  ocessor macro de
16600 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54 45  fined..** SQLITE
16610 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16620 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
16630 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
16640 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
16650 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
16660 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
16670 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
16680 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  eap..** </dl>.*/
16690 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
166a0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
166b0 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
166c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
166d0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
166e0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
166f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16700 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
16710 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
16720 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16730 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
16740 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
16750 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
16760 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16770 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16780 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
16790 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
167a0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
167b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
167c0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
167d0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
167e0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
167f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16800 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
16810 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
16820 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
16830 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16840 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
16850 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
16860 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
16870 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16880 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
16890 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
168a0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
168b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
168c0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
168d0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
168e0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
168f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16900 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
16910 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
16920 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
16930 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
16940 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
16950 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
16960 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
16970 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
16980 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
16990 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
169a0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
169b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
169c0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
169d0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
169e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
169f0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
16a00 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
16a10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16a20 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
16a30 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
16a40 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
16a50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16a60 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
16a70 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
16a80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16a90 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
16aa0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
16ab0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
16ac0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16ad0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
16ae0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
16af0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
16b00 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16b10 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
16b20 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
16b30 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
16b40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16b50 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
16b60 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
16b70 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
16b80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16b90 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
16ba0 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
16bb0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
16bc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16bd0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
16be0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
16bf0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
16c00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16c10 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
16c20 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
16c30 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
16c40 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
16c50 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
16c60 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
16c70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16c80 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
16c90 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
16ca0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16cb0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
16cc0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
16cd0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
16ce0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16cf0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
16d00 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
16d10 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
16d20 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
16d30 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16d40 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
16d50 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
16d60 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
16d70 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
16d80 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
16d90 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16da0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
16db0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
16dc0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
16dd0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16de0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
16df0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
16e00 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
16e10 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
16e20 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
16e30 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
16e40 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
16e50 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
16e60 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
16e70 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16e80 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
16e90 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16ea0 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
16eb0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
16ec0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
16ed0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
16ee0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
16ef0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
16f00 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
16f10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16f20 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
16f30 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
16f40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16f50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
16f60 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
16f70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
16f80 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
16f90 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
16fa0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
16fb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16fc0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
16fd0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16fe0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
16ff0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
17000 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
17010 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
17020 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
17030 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
17040 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
17050 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
17060 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
17070 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
17080 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
17090 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
170a0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
170b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
170c0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
170d0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
170e0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
170f0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
17100 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
17110 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
17120 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
17130 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
17140 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
17150 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
17160 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
17170 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
17180 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
17190 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
171a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
171b0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
171c0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
171d0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
171e0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
171f0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
17200 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
17210 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
17220 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
17230 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
17240 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
17250 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
17260 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
17270 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
17280 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
17290 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
172a0 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
172b0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
172c0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
172d0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
172e0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
172f0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
17300 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17310 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
17320 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
17330 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
17340 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
17350 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
17360 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
17370 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
17380 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
17390 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
173a0 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
173b0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
173c0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
173d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
173e0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
173f0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
17400 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
17410 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
17420 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
17430 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
17440 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
17450 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
17460 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
17470 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
17480 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
17490 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
174a0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
174b0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
174c0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
174d0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
174e0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
174f0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
17500 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
17510 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
17520 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
17530 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17540 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17550 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17560 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17570 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17580 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
17590 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
175a0 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
175b0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
175c0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
175d0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
175e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
175f0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
17600 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
17610 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
17620 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17630 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17640 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17650 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
17660 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17670 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
17680 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17690 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
176a0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
176b0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
176c0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
176d0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
176e0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
176f0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17700 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17710 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
17720 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
17730 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
17740 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
17750 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
17760 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
17770 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17780 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17790 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
177a0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
177b0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
177c0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
177d0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
177e0 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
177f0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
17800 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17810 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17820 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17830 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17840 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17850 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
17860 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
17870 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
17880 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
17890 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
178a0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
178b0 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
178c0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
178d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
178e0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
178f0 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
17900 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
17910 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
17920 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
17930 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
17940 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
17950 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
17960 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
17970 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
17980 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
17990 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
179a0 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
179b0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
179c0 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
179d0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
179e0 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
179f0 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
17a00 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
17a10 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
17a20 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
17a30 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
17a40 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
17a50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
17a60 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
17a70 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
17a80 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
17a90 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
17aa0 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
17ab0 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45  t Rowid.**.** ^E
17ac0 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73  ach entry in mos
17ad0 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20  t SQLite tables 
17ae0 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54  (except for [WIT
17af0 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
17b00 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69  es).** has a uni
17b10 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
17b20 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
17b30 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
17b40 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
17b50 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
17b60 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
17b70 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
17b80 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
17b90 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
17ba0 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
17bb0 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
17bc0 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
17bd0 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
17be0 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
17bf0 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
17c00 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
17c10 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
17c20 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
17c30 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
17c40 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
17c50 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
17c60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
17c70 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17c80 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66  _rowid(D) interf
17c90 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
17ca0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a  [rowid] of the .
17cb0 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  ** most recent s
17cc0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
17cd0 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20  T] into a rowid 
17ce0 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61  table or [virtua
17cf0 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64  l table].** on d
17d00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17d10 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74  on D..** ^Insert
17d20 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20  s into [WITHOUT 
17d30 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72  ROWID] tables ar
17d40 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a  e not recorded..
17d50 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  ** ^If no succes
17d60 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69  sful [INSERT]s i
17d70 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
17d80 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
17d90 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61  curred on the da
17da0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17db0 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71  n D, .** then sq
17dc0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17dd0 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
17de0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
17df0 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
17e00 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
17e10 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69  trigger or withi
17e20 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  n a [virtual tab
17e30 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74  le].** method, t
17e40 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
17e50 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
17e60 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
17e70 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
17e80 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
17e90 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
17ea0 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69  l table method i
17eb0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
17ec0 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
17ed0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
17ee0 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c  ble method ends,
17ef0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17f00 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
17f10 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
17f20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
17f30 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
17f40 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20  r or virtual.** 
17f50 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67  table method beg
17f60 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  an.)^.**.** ^An 
17f70 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
17f80 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
17f90 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
17fa0 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
17fb0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17fc0 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
17fd0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
17fe0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
17ff0 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
18000 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
18010 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
18020 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
18030 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
18040 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
18050 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
18060 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
18070 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
18080 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
18090 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
180a0 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
180b0 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
180c0 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
180d0 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
180e0 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
180f0 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
18100 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
18110 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
18120 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
18130 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
18140 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
18150 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
18160 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
18170 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
18180 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
18190 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
181a0 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
181b0 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
181c0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
181d0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
181e0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
181f0 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
18200 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
18210 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
18220 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
18230 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
18240 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
18250 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
18260 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
18270 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
18280 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
18290 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
182a0 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
182b0 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
182c0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
182d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
182e0 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
182f0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
18300 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
18310 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
18320 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
18330 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
18340 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
18350 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18360 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
18370 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
18380 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
18390 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
183a0 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
183b0 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
183c0 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
183d0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
183e0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
183f0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
18400 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
18410 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
18420 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18430 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
18440 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
18450 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
18460 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
18470 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
18480 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
18490 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
184a0 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
184b0 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
184c0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
184d0 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
184e0 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
184f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18500 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
18510 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
18520 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79  meter..** ^(Only
18530 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
18540 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
18550 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
18560 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
18570 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
18580 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
18590 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
185a0 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
185b0 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
185c0 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
185d0 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
185e0 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74  counted.)^ Use t
185f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
18600 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
18610 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64  function to find
18620 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
18630 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20  r of changes.** 
18640 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
18650 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
18660 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e  gers and foreign
18670 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a   key actions..**
18680 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  .** ^Changes to 
18690 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
186a0 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20  simulated by an 
186b0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
186c0 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ger].** are not 
186d0 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72  counted.  Only r
186e0 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65  eal table change
186f0 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
18700 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68  *.** ^(A "row ch
18710 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
18720 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
18730 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
18740 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
18750 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
18760 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
18770 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
18780 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
18790 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
187a0 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20  ts of [REPLACE] 
187b0 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
187c0 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
187d0 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
187e0 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c  sing, [DROP TABL
187f0 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  E], or by any ot
18800 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
18810 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
18820 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
18830 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  nges.)^.**.** A 
18840 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
18850 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
18860 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
18870 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
18880 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
18890 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
188a0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
188b0 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
188c0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
188d0 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
188e0 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
188f0 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
18900 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
18910 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
18920 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
18930 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
18940 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
18950 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
18960 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
18970 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
18980 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
18990 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
189a0 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
189b0 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
189c0 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
189d0 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65  ^Calling [sqlite
189e0 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
189f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
18a00 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
18a10 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
18a20 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
18a30 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  xt..**.** ^This 
18a40 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
18a50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
18a60 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
18a70 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
18a80 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
18a90 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
18aa0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
18ab0 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
18ac0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
18ad0 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65  **.** ^Thus, whe
18ae0 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
18af0 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
18b00 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
18b10 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
18b20 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
18b30 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
18b40 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
18b50 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
18b60 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
18b70 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
18b80 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62    ^(Within the b
18b90 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
18ba0 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
18bb0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
18bc0 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  face can be call
18bd0 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
18be0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
18bf0 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
18c00 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
18c10 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
18c20 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
18c30 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
18c40 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
18c50 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
18c60 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
18c70 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
18c80 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
18c90 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
18ca0 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
18cb0 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76   since those hav
18cc0 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
18cd0 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ext.)^.**.** See
18ce0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
18cf0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
18d00 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
18d10 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
18d20 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
18d30 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
18d40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
18d50 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
18d60 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
18d70 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
18d80 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
18d90 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
18da0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
18db0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
18dc0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
18dd0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
18de0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
18df0 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
18e00 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
18e10 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
18e20 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
18e30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
18e40 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
18e50 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
18e60 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
18e70 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
18e80 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
18e90 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
18ea0 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
18eb0 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
18ec0 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
18ed0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
18ee0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
18ef0 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
18f00 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
18f10 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
18f20 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
18f30 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
18f40 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
18f50 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
18f60 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
18f70 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
18f80 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
18f90 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
18fa0 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
18fb0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
18fc0 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
18fd0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
18fe0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
18ff0 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
19000 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
19010 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
19020 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
19030 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
19040 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
19050 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
19060 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
19070 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
19080 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
19090 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
190a0 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
190b0 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
190c0 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
190d0 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
190e0 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
190f0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
19100 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
19110 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
19120 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
19130 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
19140 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
19150 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
19160 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
19170 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
19180 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
19190 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
191a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
191b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
191c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
191d0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
191e0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
191f0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
19200 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
19210 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
19220 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
19230 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
19240 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
19250 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
19260 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19270 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
19280 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
19290 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
192a0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
192b0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
192c0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
192d0 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
192e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
192f0 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
19300 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
19310 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19320 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
19330 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
19340 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
19350 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
19360 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
19370 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
19380 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
19390 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
193a0 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
193b0 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
193c0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
193d0 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
193e0 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
193f0 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
19400 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
19410 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
19420 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
19430 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
19440 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
19450 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
19460 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
19470 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
19480 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
19490 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
194a0 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
194b0 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
194c0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
194d0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
194e0 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
194f0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
19500 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
19510 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
19520 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
19530 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
19540 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
19550 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
19560 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
19570 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
19580 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
19590 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
195a0 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
195b0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
195c0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
195d0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
195e0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
195f0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
19600 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
19610 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
19620 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
19630 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
19640 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
19650 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
19660 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
19670 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
19680 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
19690 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
196a0 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
196b0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
196c0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
196d0 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
196e0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
196f0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
19700 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
19710 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
19720 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
19730 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
19740 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
19750 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
19760 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
19770 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
19780 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
19790 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
197a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
197b0 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
197c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
197d0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
197e0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
197f0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19800 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
19810 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
19820 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
19830 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
19840 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
19850 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
19860 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
19870 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
19880 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
19890 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
198a0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
198b0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
198c0 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
198d0 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
198e0 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
198f0 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
19900 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
19910 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
19920 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
19930 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
19940 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
19950 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
19960 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
19970 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
19980 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
19990 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
199a0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
199b0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
199c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
199d0 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
199e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
199f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19a00 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
19a10 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
19a20 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
19a30 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
19a40 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
19a50 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  happen..*/.SQLIT
19a60 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
19a70 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
19a80 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
19a90 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
19aa0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
19ab0 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
19ac0 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
19ad0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
19ae0 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
19af0 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
19b00 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
19b10 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
19b20 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
19b30 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
19b40 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
19b50 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
19b60 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
19b70 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
19b80 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
19b90 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
19ba0 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
19bb0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
19bc0 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
19bd0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
19be0 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
19bf0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
19c00 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
19c10 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
19c20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
19c30 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
19c40 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
19c50 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
19c60 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
19c70 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
19c80 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
19c90 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
19ca0 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
19cb0 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
19cc0 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
19cd0 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
19ce0 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
19cf0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
19d00 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
19d10 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
19d20 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
19d30 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
19d40 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
19d50 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
19d60 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
19d70 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
19d80 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
19d90 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
19da0 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
19db0 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
19dc0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
19dd0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
19de0 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
19df0 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
19e00 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
19e10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
19e20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
19e30 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
19e40 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
19e50 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
19e60 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
19e70 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
19e80 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
19e90 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
19ea0 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
19eb0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
19ec0 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
19ed0 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
19ee0 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
19ef0 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
19f00 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
19f10 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19f20 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
19f30 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
19f40 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
19f50 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
19f60 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
19f70 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
19f80 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
19f90 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
19fa0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
19fb0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19fc0 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
19fd0 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
19fe0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
19ff0 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
1a000 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
1a010 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
1a020 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1a030 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
1a040 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1a050 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
1a060 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
1a070 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1a080 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
1a090 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1a0a0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1a0b0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
1a0c0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1a0d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1a0e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1a0f0 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
1a100 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  sql);.SQLITE_API
1a110 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d   int sqlite3_com
1a120 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
1a130 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
1a140 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
1a150 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
1a160 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
1a170 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a  BUSY Errors.**.*
1a180 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1a190 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
1a1a0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
1a1b0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1a1c0 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
1a1d0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1a1e0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
1a1f0 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
1a200 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
1a210 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
1a220 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ked..**.** ^If t
1a230 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1a240 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
1a250 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
1a260 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
1a270 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
1a280 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1a290 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
1a2a0 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
1a2b0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1a2c0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1a2d0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1a2e0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1a2f0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1a300 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1a310 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1a320 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1a330 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1a340 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1a350 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1a360 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1a370 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1a380 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1a390 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1a3a0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1a3b0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1a3c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1a3d0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1a3e0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1a3f0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1a400 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
1a410 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
1a420 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
1a430 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
1a440 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
1a450 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
1a460 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
1a470 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
1a480 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
1a490 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
1a4a0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
1a4b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
1a4c0 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
1a4d0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1a4e0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
1a4f0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
1a500 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
1a510 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
1a520 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
1a530 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
1a540 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
1a550 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
1a560 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
1a570 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
1a580 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
1a590 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
1a5a0 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
1a5b0 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
1a5c0 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
1a5d0 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
1a5e0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
1a5f0 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
1a600 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
1a610 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
1a620 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1a630 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
1a640 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
1a650 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
1a660 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1a670 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
1a680 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
1a690 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1a6a0 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
1a6b0 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
1a6c0 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
1a6d0 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
1a6e0 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
1a6f0 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
1a700 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
1a710 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
1a720 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
1a730 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
1a740 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
1a750 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
1a760 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
1a770 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1a780 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
1a790 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
1a7a0 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
1a7b0 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
1a7c0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1a7d0 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
1a7e0 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
1a7f0 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
1a800 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
1a810 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
1a820 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
1a830 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
1a840 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
1a850 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
1a860 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
1a870 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
1a880 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
1a890 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
1a8a0 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
1a8b0 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
1a8c0 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
1a8d0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1a8e0 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
1a8f0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1a900 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1a910 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
1a920 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
1a930 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
1a940 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
1a950 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
1a960 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
1a970 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
1a980 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
1a990 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
1a9a0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
1a9b0 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
1a9c0 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
1a9d0 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
1a9e0 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
1a9f0 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
1aa00 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
1aa10 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
1aa20 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
1aa30 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
1aa40 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
1aa50 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
1aa60 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
1aa70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
1aa80 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
1aa90 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
1aaa0 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69   readers.  ^If i
1aab0 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
1aac0 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
1aad0 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
1aae0 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
1aaf0 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
1ab00 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
1ab10 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
1ab20 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
1ab30 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
1ab40 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
1ab50 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
1ab60 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
1ab70 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
1ab80 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
1ab90 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65  ^This error code
1aba0 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
1abb0 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
1abc0 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
1abd0 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
1abe0 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
1abf0 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
1ac00 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
1ac10 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
1ac20 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
1ac30 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
1ac40 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
1ac50 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
1ac60 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
1ac70 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
1ac80 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1ac90 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1aca0 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
1acb0 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
1acc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1acd0 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
1ace0 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
1acf0 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
1ad00 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
1ad10 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
1ad20 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
1ad30 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1ad40 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
1ad50 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
1ad60 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1ad70 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
1ad80 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
1ad90 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
1ada0 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
1adb0 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
1adc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1add0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1ade0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41  busy handler.  A
1adf0 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
1ae00 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
1ae10 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
1ae20 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
1ae30 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
1ae40 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
1ae50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1ae60 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
1ae70 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
1ae80 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1ae90 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54  andler..*/.SQLIT
1aea0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1aeb0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1aec0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
1aed0 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
1aee0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1aef0 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1af00 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
1af10 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
1af20 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
1af30 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
1af40 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
1af50 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
1af60 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
1af70 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
1af80 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
1af90 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
1afa0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
1afb0 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
1afc0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1afd0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1afe0 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
1aff0 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
1b000 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
1b010 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1b020 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
1b030 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
1b040 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
1b050 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
1b060 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
1b070 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
1b080 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
1b090 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
1b0a0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
1b0b0 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
1b0c0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
1b0d0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
1b0e0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
1b0f0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
1b100 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1b110 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1b120 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1b130 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
1b140 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1b150 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
1b160 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
1b170 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
1b180 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
1b190 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
1b1a0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1b1b0 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
1b1c0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1b1d0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1b1e0 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1b1f0 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1b200 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
1b210 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73   int sqlite3_bus
1b220 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
1b230 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
1b240 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1b250 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
1b260 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
1b270 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69  ueries.**.** Thi
1b280 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
1b290 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
1b2a0 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
1b2b0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1b2c0 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
1b2d0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1b2e0 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
1b2f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
1b300 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
1b310 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
1b320 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
1b330 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
1b340 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1b350 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
1b360 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
1b370 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
1b380 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
1b390 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
1b3a0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
1b3b0 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
1b3c0 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
1b3d0 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
1b3e0 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
1b3f0 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
1b400 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
1b410 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
1b420 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
1b430 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
1b440 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
1b450 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
1b460 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
1b470 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
1b480 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
1b490 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
1b4a0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1b4b0 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
1b4c0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1b4d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b4e0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1b4f0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1b500 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1b510 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1b520 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1b530 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1b540 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1b550 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1b560 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1b570 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1b580 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1b590 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1b5a0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1b5b0 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1b5c0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1b5d0 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1b5e0 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1b5f0 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1b600 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b610 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1b620 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1b630 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1b640 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1b650 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1b660 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1b670 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1b680 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1b690 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1b6a0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1b6b0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1b6c0 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1b6d0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1b6e0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1b6f0 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1b700 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1b710 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1b720 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1b730 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1b740 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1b750 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1b760 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1b770 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1b780 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1b790 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1b7a0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1b7b0 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1b7c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b7d0 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1b7e0 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1b7f0 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1b800 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1b810 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1b820 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1b830 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b840 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1b850 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1b860 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1b870 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1b880 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1b890 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1b8a0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1b8b0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1b8c0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1b8d0 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1b8e0 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1b8f0 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1b900 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1b910 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1b920 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b930 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1b940 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1b950 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1b960 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1b970 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1b980 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1b990 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b9a0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1b9b0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b9c0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1b9d0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b9e0 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1b9f0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1ba00 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1ba10 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1ba20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1ba30 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1ba40 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1ba50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ba60 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1ba70 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1ba80 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1ba90 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1baa0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1bab0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1bac0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1bad0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
1bae0 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
1baf0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
1bb00 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
1bb10 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
1bb20 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
1bb30 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1bb40 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
1bb50 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
1bb60 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
1bb70 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
1bb80 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
1bb90 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
1bba0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
1bbb0 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
1bbc0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
1bbd0 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
1bbe0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1bbf0 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
1bc00 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
1bc10 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
1bc20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1bc30 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
1bc40 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1bc50 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
1bc60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
1bc70 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
1bc80 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
1bc90 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
1bca0 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
1bcb0 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
1bcc0 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
1bcd0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
1bce0 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
1bcf0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1bd00 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
1bd10 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
1bd20 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
1bd30 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
1bd40 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
1bd50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1bd60 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
1bd70 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
1bd80 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
1bd90 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
1bda0 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
1bdb0 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
1bdc0 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
1bdd0 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
1bde0 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
1bdf0 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
1be00 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
1be10 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
1be20 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
1be30 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
1be40 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
1be50 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
1be60 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
1be70 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
1be80 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1be90 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1bea0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
1beb0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1bec0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1bed0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1bee0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1bef0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1bf00 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1bf10 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1bf20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1bf30 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1bf40 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1bf50 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1bf60 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1bf70 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1bf80 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1bf90 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1bfa0 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1bfb0 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1bfc0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1bfd0 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1bfe0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1bff0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1c000 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1c010 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1c020 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1c030 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
1c040 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1c050 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1c060 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1c070 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1c080 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1c090 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1c0a0 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1c0b0 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1c0c0 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1c0d0 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1c0e0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1c0f0 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
1c100 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1c110 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
1c120 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
1c130 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
1c140 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
1c150 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1c160 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1c170 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
1c180 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1c190 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
1c1a0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
1c1b0 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
1c1c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1c1d0 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
1c1e0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
1c1f0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
1c200 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1c210 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1c220 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1c230 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1c240 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1c250 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1c260 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1c270 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1c280 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1c290 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1c2a0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1c2b0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1c2c0 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1c2d0 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1c2e0 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1c2f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1c300 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1c310 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1c320 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1c330 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1c340 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1c350 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1c360 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1c370 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1c380 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1c390 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1c3a0 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1c3b0 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1c3c0 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1c3d0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1c3e0 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1c3f0 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1c400 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1c410 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1c420 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1c430 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1c440 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1c450 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1c460 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1c470 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1c480 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1c490 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1c4a0 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1c4b0 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1c4c0 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1c4d0 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1c4e0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1c4f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1c500 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1c510 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1c520 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1c530 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1c540 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1c550 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1c560 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1c570 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1c580 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1c590 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1c5a0 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1c5b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1c5c0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1c5d0 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1c5e0 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1c5f0 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1c600 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1c610 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1c620 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1c630 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1c640 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1c650 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1c660 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1c670 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1c680 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1c690 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1c6a0 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1c6b0 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1c6c0 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1c6d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1c6e0 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
1c6f0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
1c700 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
1c710 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
1c720 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
1c730 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
1c740 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
1c750 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
1c760 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
1c770 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
1c780 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
1c790 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
1c7a0 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
1c7b0 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1c7c0 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1c7d0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1c7e0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1c7f0 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1c800 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1c810 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1c820 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1c830 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1c840 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1c850 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1c860 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1c870 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1c880 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1c890 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1c8a0 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1c8b0 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1c8c0 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1c8d0 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1c8e0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1c8f0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1c900 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1c910 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1c920 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1c930 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1c940 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1c950 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c960 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1c970 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1c980 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1c990 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c9a0 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1c9b0 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1c9c0 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1c9d0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c9e0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c9f0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1ca00 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1ca10 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1ca20 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1ca30 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1ca40 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1ca50 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1ca60 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1ca70 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1ca80 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1ca90 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1caa0 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1cab0 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1cac0 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1cad0 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1cae0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1caf0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1cb00 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1cb10 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1cb20 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1cb30 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1cb40 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1cb50 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1cb60 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1cb70 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1cb80 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1cb90 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1cba0 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1cbb0 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1cbc0 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1cbd0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1cbe0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1cbf0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1cc00 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1cc10 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1cc20 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1cc30 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1cc40 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1cc50 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1cc60 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1cc70 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1cc80 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1cc90 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1cca0 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1ccb0 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1ccc0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1ccd0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1cce0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1ccf0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1cd00 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1cd10 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1cd20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1cd30 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1cd40 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1cd50 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1cd60 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1cd70 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1cd80 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1cd90 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1cda0 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1cdb0 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1cdc0 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1cdd0 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1cde0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1cdf0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1ce00 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1ce10 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1ce20 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1ce30 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1ce40 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1ce50 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1ce60 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1ce70 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1ce80 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1ce90 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1cea0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1ceb0 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1cec0 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1ced0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1cee0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1cef0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1cf00 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1cf10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1cf20 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
1cf30 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1cf40 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
1cf50 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
1cf60 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
1cf70 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
1cf80 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
1cf90 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
1cfa0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
1cfb0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
1cfc0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
1cfd0 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
1cfe0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  /.SQLITE_API cha
1cff0 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1d000 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1d010 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1d020 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1d030 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1d040 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51  r*, va_list);.SQ
1d050 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1d060 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1d070 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1d080 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
1d090 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1d0a0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1d0b0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1d0c0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1d0d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d0e0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1d0f0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1d100 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1d110 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1d120 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1d130 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1d140 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1d150 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1d160 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1d170 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1d180 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1d190 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1d1a0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1d1b0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1d1c0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1d1d0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1d1e0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1d1f0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1d200 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1d210 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d220 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1d230 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1d240 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1d250 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1d260 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1d270 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1d280 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1d290 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1d2a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1d2b0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1d2c0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1d2d0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1d2e0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1d2f0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1d300 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1d310 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1d320 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1d330 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1d340 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1d350 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1d360 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
1d370 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
1d380 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
1d390 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
1d3a0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1d3b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1d3c0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1d3d0 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
1d3e0 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
1d3f0 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
1d400 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
1d410 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
1d420 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
1d430 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
1d440 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
1d450 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
1d460 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
1d470 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1d480 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
1d490 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
1d4a0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
1d4b0 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
1d4c0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
1d4d0 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
1d4e0 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
1d4f0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
1d500 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
1d510 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
1d520 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1d530 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
1d540 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
1d550 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1d560 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
1d570 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
1d580 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
1d590 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
1d5a0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
1d5b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
1d5c0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
1d5d0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1d5e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1d5f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d600 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1d610 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1d620 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1d630 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1d640 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1d650 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1d660 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1d670 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1d680 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1d690 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
1d6a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
1d6b0 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
1d6c0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1d6d0 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
1d6e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1d6f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1d700 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
1d710 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1d720 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
1d730 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
1d740 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1d750 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
1d760 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
1d770 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1d780 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1d790 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
1d7a0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1d7b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d7c0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1d7d0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1d7e0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1d7f0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1d800 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1d810 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
1d820 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
1d830 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1d840 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1d850 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1d860 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
1d870 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1d880 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1d890 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1d8a0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1d8b0 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
1d8c0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
1d8d0 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
1d8e0 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1d8f0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1d900 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1d910 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1d920 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1d930 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1d940 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1d950 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1d960 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1d970 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d980 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1d990 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1d9a0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1d9b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1d9c0 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
1d9d0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1d9e0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
1d9f0 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
1da00 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1da10 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1da20 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
1da30 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
1da40 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
1da50 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
1da60 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
1da70 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
1da80 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
1da90 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
1daa0 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
1dab0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
1dac0 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
1dad0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
1dae0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
1daf0 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
1db00 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
1db10 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
1db20 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
1db30 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
1db40 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
1db50 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
1db60 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
1db70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
1db80 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
1db90 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
1dba0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
1dbb0 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
1dbc0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1dbd0 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
1dbe0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
1dbf0 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
1dc00 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
1dc10 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
1dc20 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
1dc30 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
1dc40 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1dc50 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
1dc60 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
1dc70 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
1dc80 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
1dc90 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
1dca0 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
1dcb0 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
1dcc0 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
1dcd0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
1dce0 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
1dcf0 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
1dd00 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
1dd10 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
1dd20 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
1dd30 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
1dd40 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
1dd50 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
1dd60 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
1dd70 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
1dd80 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
1dd90 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
1dda0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
1ddb0 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
1ddc0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1ddd0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
1dde0 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
1ddf0 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
1de00 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
1de10 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
1de20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1de30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1de40 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
1de50 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
1de60 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
1de70 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1de80 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
1de90 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
1dea0 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
1deb0 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
1dec0 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
1ded0 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
1dee0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
1def0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1df00 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  c()]..*/.SQLITE_
1df10 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
1df20 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53  3_malloc(int);.S
1df30 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1df40 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1df50 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  void*, int);.SQL
1df60 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1df70 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1df80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1df90 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1dfa0 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1dfb0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1dfc0 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1dfd0 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1dfe0 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1dff0 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1e000 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1e010 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1e020 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1e030 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1e040 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1e050 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1e060 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1e070 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1e080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1e090 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1e0a0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1e0b0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1e0c0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1e0d0 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1e0e0 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1e0f0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1e100 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1e110 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1e120 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1e130 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1e140 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1e150 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1e160 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1e170 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1e180 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1e190 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1e1a0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1e1b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1e1c0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1e1d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1e1e0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1e1f0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1e200 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1e210 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1e220 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1e230 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1e240 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1e250 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1e260 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1e270 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1e280 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1e290 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1e2a0 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1e2b0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1e2c0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1e2d0 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1e2e0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1e2f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1e300 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1e310 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1e320 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1e330 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1e340 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1e350 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1e360 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1e370 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1e380 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1e390 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1e3a0 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1e3b0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51  the reset..*/.SQ
1e3c0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
1e3d0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1e3e0 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1e3f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
1e400 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1e410 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1e420 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1e430 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1e440 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1e450 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1e460 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1e470 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1e480 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1e490 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1e4a0 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1e4b0 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1e4c0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1e4d0 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1e4e0 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1e4f0 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1e500 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1e510 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1e520 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1e530 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1e540 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1e550 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1e560 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1e570 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1e580 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1e590 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1e5a0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1e5b0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1e5c0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1e5d0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1e5e0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1e5f0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1e600 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1e610 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1e620 72 20 50 2e 0a 2a 2a 20 5e 49 66 20 4e 20 69 73  r P..** ^If N is
1e630 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c 20   less than one, 
1e640 74 68 65 6e 20 50 20 63 61 6e 20 62 65 20 61 20  then P can be a 
1e650 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1e660 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75  .** ^If this rou
1e670 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65  tine has not bee
1e680 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c  n previously cal
1e690 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72  led or if the pr
1e6a0 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68  evious.** call h
1e6b0 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f  ad N less than o
1e6c0 6e 65 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e  ne, then the PRN
1e6d0 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
1e6e0 67 20 72 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20  g randomness.** 
1e6f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68  obtained from th
1e700 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
1e710 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
1e720 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1e730 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66  ] object..** ^If
1e740 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
1e750 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1e760 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31  ne had an N of 1
1e770 20 6f 72 20 6d 6f 72 65 20 74 68 65 6e 0a 2a 2a   or more then.**
1e780 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
1e790 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
1e7a0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
1e7b0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
1e7c0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
1e7d0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
1e7e0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
1e7f0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
1e800 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61   void sqlite3_ra
1e810 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1e820 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1e830 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1e840 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1e850 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1e860 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1e870 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1e880 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e890 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1e8a0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1e8b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1e8c0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1e8d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1e8e0 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1e8f0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1e900 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1e910 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1e920 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1e930 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1e940 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1e950 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1e960 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1e970 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1e980 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1e990 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e9a0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1e9b0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1e9c0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1e9d0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1e9e0 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1e9f0 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1ea00 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1ea10 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1ea20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1ea30 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1ea40 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1ea50 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1ea60 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1ea70 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1ea80 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1ea90 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1eaa0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1eab0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1eac0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1ead0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1eae0 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1eaf0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1eb00 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1eb10 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1eb20 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1eb30 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1eb40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1eb50 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1eb60 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1eb70 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1eb80 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1eb90 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1eba0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1ebb0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1ebc0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1ebd0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1ebe0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1ebf0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1ec00 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1ec10 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1ec20 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1ec30 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1ec40 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1ec50 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1ec60 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1ec70 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1ec80 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1ec90 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1eca0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1ecb0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1ecc0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1ecd0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1ece0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ecf0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1ed00 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1ed10 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1ed20 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1ed30 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1ed40 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1ed50 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1ed60 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1ed70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1ed80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ed90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1eda0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1edb0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1edc0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1edd0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1ede0 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1edf0 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1ee00 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1ee10 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1ee20 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1ee30 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1ee40 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1ee50 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1ee60 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1ee70 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1ee80 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1ee90 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1eea0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1eeb0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1eec0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1eed0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1eee0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1eef0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1ef00 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1ef10 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1ef20 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1ef30 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1ef40 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1ef50 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1ef60 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1ef70 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1ef80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1ef90 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1efa0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1efb0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1efc0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1efd0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1efe0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1eff0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1f000 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1f010 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1f020 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1f030 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1f040 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1f050 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1f060 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1f070 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1f080 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1f090 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1f0a0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1f0b0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1f0c0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1f0d0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1f0e0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1f0f0 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1f100 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1f110 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1f120 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1f130 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1f140 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1f150 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1f160 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1f170 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1f180 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1f190 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1f1a0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1f1b0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1f1c0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1f1d0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1f1e0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1f1f0 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1f200 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1f210 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1f220 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1f230 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1f240 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1f250 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1f260 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1f270 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1f280 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1f290 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1f2a0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1f2b0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1f2c0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1f2d0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1f2e0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1f2f0 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1f300 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1f310 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1f320 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1f330 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1f340 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1f350 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1f360 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1f370 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1f380 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1f390 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1f3a0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1f3b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1f3c0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1f3d0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1f3e0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1f3f0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1f400 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1f410 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1f420 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1f430 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1f440 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1f450 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1f460 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1f470 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1f480 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1f490 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1f4a0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1f4b0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1f4c0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1f4d0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1f4e0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1f4f0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1f500 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1f510 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1f520 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1f530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f540 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1f550 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1f560 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1f570 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1f580 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1f590 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1f5a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1f5b0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1f5c0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1f5d0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1f5e0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1f5f0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1f600 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f610 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1f620 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1f630 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1f640 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1f650 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1f660 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1f670 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1f680 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1f690 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f6a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1f6b0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1f6c0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1f6d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1f6e0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1f6f0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1f700 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1f710 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1f720 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f730 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1f740 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1f750 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1f760 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1f770 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1f780 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f790 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1f7a0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1f7b0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1f7c0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1f7d0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1f7e0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1f7f0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1f800 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1f810 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1f820 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1f830 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1f840 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f850 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1f860 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1f870 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1f880 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1f890 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1f8a0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1f8b0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1f8c0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1f8d0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1f8e0 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1f8f0 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1f900 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1f910 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1f920 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1f930 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f940 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1f950 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1f960 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1f970 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
1f980 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74   int sqlite3_set
1f990 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1f9a0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1f9b0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1f9c0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1f9d0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1f9e0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1f9f0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1fa00 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1fa10 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1fa20 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1fa30 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1fa40 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1fa50 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1fa60 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1fa70 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1fa80 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1fa90 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1faa0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1fab0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1fac0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1fad0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1fae0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1faf0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1fb00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1fb10 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1fb20 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1fb30 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1fb40 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1fb50 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1fb60 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1fb70 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1fb80 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1fb90 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1fba0 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1fbb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1fbc0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1fbd0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1fbe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1fbf0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1fc00 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1fc10 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1fc20 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1fc30 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1fc40 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1fc50 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1fc60 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1fc70 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1fc80 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1fc90 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1fca0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1fcb0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1fcc0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1fcd0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1fce0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1fcf0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1fd00 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1fd10 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1fd20 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1fd30 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1fd40 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1fd50 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1fd60 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1fd70 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1fd80 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1fd90 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1fda0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1fdb0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1fdc0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1fdd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1fde0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1fdf0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1fe00 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1fe10 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1fe20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1fe30 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1fe40 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1fe50 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1fe60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1fe70 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1fe80 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1fe90 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1fea0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1feb0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1fec0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1fed0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1fee0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1fef0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1ff00 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1ff10 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1ff20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1ff30 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1ff40 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1ff50 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1ff60 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1ff70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1ff80 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ff90 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1ffa0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1ffb0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1ffc0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1ffd0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1ffe0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1fff0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
20000 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
20010 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
20020 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
20030 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
20040 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20050 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20060 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
20070 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
20080 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
20090 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
200a0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
200b0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
200c0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
200d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
200e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
200f0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
20100 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20110 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20120 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20130 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
20140 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
20150 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
20160 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20170 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20180 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
20190 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
201a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
201b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
201c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
201d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
201e0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
201f0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
20200 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
20210 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20220 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
20230 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
20240 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
20250 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20260 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20270 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
20280 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
20290 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
202a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
202b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
202c0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
202d0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
202e0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
202f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20300 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20310 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
20320 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
20330 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20340 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20350 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20360 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
20370 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
20380 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
20390 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
203a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
203b0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
203c0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
203d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
203e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
203f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20400 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
20410 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
20420 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
20430 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20440 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20450 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
20460 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
20470 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
20480 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20490 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
204a0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
204b0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
204c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
204d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
204e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
204f0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
20500 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
20510 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
20520 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20530 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
20540 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
20550 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
20560 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
20570 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
20580 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
20590 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
205a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
205b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
205c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
205d0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
205e0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
205f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20600 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20610 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20620 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
20630 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
20640 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
20650 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
20660 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
20670 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
20680 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
20690 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
206a0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
206b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
206c0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
206d0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
206e0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
206f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20700 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20710 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
20720 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
20730 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
20740 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20750 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20760 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
20770 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
20780 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20790 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
207a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
207b0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
207c0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
207d0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
207e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
207f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20800 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
20810 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
20820 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
20830 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20850 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
20860 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
20870 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
20880 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
20890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
208a0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
208b0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
208c0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
208d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
208e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
208f0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
20900 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
20910 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
20920 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
20940 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
20950 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
20960 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
20970 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
20980 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
20990 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
209a0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
209b0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
209c0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
209d0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
209e0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
209f0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
20a00 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
20a10 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
20a20 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
20a30 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
20a40 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
20a50 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
20a60 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
20a70 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
20a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
20a90 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
20aa0 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
20ab0 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45  SQLITE_RECURSIVE
20ac0 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20              33  
20ad0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
20ae0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20af0 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41      */../*.** CA
20b00 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
20b10 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
20b20 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
20b30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
20b40 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
20b50 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
20b60 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
20b70 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
20b80 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
20b90 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
20ba0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
20bb0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
20bc0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
20bd0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
20be0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
20bf0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
20c00 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
20c10 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
20c20 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
20c30 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
20c40 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
20c50 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
20c60 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
20c70 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
20c80 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
20c90 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
20ca0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
20cb0 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
20cc0 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
20cd0 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
20ce0 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
20cf0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
20d00 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
20d10 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
20d20 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
20d30 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
20d40 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
20d50 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
20d60 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
20d70 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
20d80 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
20d90 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
20da0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
20db0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
20dc0 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
20dd0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
20de0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
20df0 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
20e00 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
20e10 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
20e20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
20e30 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
20e40 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
20e50 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
20e60 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
20e70 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
20e80 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
20e90 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
20ea0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
20eb0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
20ec0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
20ed0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
20ee0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
20ef0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
20f00 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
20f10 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
20f20 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
20f30 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
20f40 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
20f50 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
20f60 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
20f70 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
20f80 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
20f90 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
20fa0 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
20fb0 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
20fc0 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
20fd0 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
20fe0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
20ff0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
21000 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
21010 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
21020 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
21030 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
21040 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
21050 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
21060 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
21070 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
21080 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
21090 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
210a0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
210b0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
210c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74   void *sqlite3_t
210d0 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
210e0 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
210f0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
21100 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
21110 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52  API SQLITE_EXPER
21120 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
21130 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
21140 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
21150 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
21160 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
21170 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
21180 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
21190 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
211a0 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
211b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
211c0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
211d0 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
211e0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
211f0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
21200 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
21210 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
21220 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
21230 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
21240 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
21250 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
21260 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
21270 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
21280 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
21290 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
212a0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
212b0 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
212c0 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
212d0 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
212e0 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
212f0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
21300 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
21310 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
21320 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
21330 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
21340 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
21350 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
21360 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
21370 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
21380 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
21390 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
213a0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
213b0 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
213c0 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
213d0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
213e0 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
213f0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
21400 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
21410 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
21420 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
21430 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
21440 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
21450 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
21460 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
21470 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
21480 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
21490 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
214a0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
214b0 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
214c0 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
214d0 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
214e0 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
214f0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
21500 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
21510 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
21520 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
21530 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
21540 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
21550 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
21560 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
21570 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
21580 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
21590 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
215a0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
215b0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
215c0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
215d0 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
215e0 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
215f0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
21600 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
21610 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
21620 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
21630 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
21640 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
21650 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21660 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
21670 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
21680 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
21690 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
216a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
216b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
216c0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
216d0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
216e0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
216f0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
21700 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
21710 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
21720 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
21730 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
21740 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
21750 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
21760 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
21770 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21780 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
21790 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
217a0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
217b0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
217c0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
217d0 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
217e0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
217f0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
21800 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
21810 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
21820 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
21830 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
21840 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
21850 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
21860 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
21870 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
21880 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
21890 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
218a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
218b0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
218c0 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
218d0 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
218e0 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
218f0 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
21900 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
21910 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
21920 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
21930 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
21940 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
21950 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
21960 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
21970 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
21980 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
21990 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
219a0 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
219b0 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
219c0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
219d0 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
219e0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
219f0 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
21a00 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
21a10 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
21a20 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
21a30 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
21a40 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
21a50 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
21a60 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
21a70 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
21a80 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
21a90 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
21aa0 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
21ab0 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
21ac0 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
21ad0 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
21ae0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
21af0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
21b00 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
21b10 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
21b20 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
21b30 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
21b40 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
21b50 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
21b60 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
21b70 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
21b80 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
21b90 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
21ba0 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
21bb0 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
21bc0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
21bd0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
21be0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
21bf0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
21c00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
21c10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
21c20 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
21c30 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
21c40 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
21c50 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
21c60 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
21c70 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
21c80 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
21c90 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
21ca0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
21cb0 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
21cc0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
21cd0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
21ce0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
21cf0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
21d00 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
21d10 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
21d20 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
21d30 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
21d40 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
21d50 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
21d60 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
21d70 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
21d80 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
21d90 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
21da0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
21db0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
21dc0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
21dd0 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
21de0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
21df0 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
21e00 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
21e10 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
21e20 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
21e30 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
21e40 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
21e50 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
21e60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21e70 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21e80 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
21e90 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
21ea0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
21eb0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
21ec0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
21ed0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
21ee0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
21ef0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
21f00 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
21f10 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
21f20 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
21f30 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
21f40 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
21f50 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
21f60 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
21f70 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
21f80 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
21f90 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
21fa0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
21fb0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
21fc0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
21fd0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
21fe0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
21ff0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
22000 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
22010 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
22020 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
22030 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
22040 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
22050 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
22060 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
22070 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
22080 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
22090 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
220a0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
220b0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
220c0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
220d0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
220e0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
220f0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
22100 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
22110 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
22120 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
22130 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
22140 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
22150 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
22160 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
22170 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
22180 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
22190 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
221a0 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
221b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
221c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
221d0 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
221e0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
221f0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
22200 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
22210 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
22220 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
22230 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
22240 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
22250 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
22260 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
22270 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
22280 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
22290 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
222a0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
222b0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
222c0 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
222d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
222e0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
222f0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
22300 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
22310 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
22320 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
22330 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
22340 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
22350 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
22360 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
22370 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
22380 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
22390 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
223a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
223b0 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
223c0 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
223d0 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
223e0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
223f0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
22400 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
22410 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
22420 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
22430 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
22440 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
22450 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
22460 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
22470 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22480 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
22490 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
224a0 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
224b0 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
224c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
224d0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
224e0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
224f0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
22500 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
22510 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
22520 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
22530 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
22540 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
22550 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
22560 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22570 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
22580 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
22590 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
225a0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
225b0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
225c0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
225d0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
225e0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
225f0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
22600 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
22610 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
22620 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
22630 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
22640 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
22650 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
22660 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
22670 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
22680 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22690 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
226a0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
226b0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
226c0 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
226d0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
226e0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
226f0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
22700 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
22710 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
22720 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
22730 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
22740 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
22750 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
22760 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
22770 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
22780 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
22790 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
227a0 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
227b0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
227c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
227d0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
227e0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
227f0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
22800 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
22810 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
22820 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
22830 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
22840 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
22850 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
22860 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
22870 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
22880 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
22890 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
228a0 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
228b0 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
228c0 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
228d0 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
228e0 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
228f0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
22900 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
22910 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
22920 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
22930 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
22940 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
22950 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
22960 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
22970 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
22980 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
22990 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
229a0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
229b0 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
229c0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
229d0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
229e0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
229f0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
22a00 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
22a10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
22a20 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
22a30 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
22a40 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
22a50 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
22a60 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
22a70 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
22a80 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
22a90 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
22aa0 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
22ab0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
22ac0 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
22ad0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
22ae0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
22af0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
22b00 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
22b10 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
22b20 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
22b30 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
22b40 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
22b50 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
22b60 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
22b70 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
22b80 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
22b90 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
22ba0 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
22bb0 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
22bc0 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
22bd0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
22be0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
22bf0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
22c00 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
22c10 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
22c20 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
22c30 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
22c40 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
22c50 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
22c60 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
22c70 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
22c80 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
22c90 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
22ca0 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
22cb0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
22cc0 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
22cd0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
22ce0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
22cf0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
22d00 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
22d10 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
22d20 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
22d30 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
22d40 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
22d50 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
22d60 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
22d70 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
22d80 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
22d90 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
22da0 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
22db0 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
22dc0 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
22dd0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
22de0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
22df0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
22e00 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
22e10 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  ** ^On windows, 
22e20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
22e30 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
22e40 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
22e50 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
22e60 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
22e70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ..**.** [[core U
22e80 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
22e90 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
22ea0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
22eb0 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
22ec0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
22ed0 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
22ee0 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
22ef0 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
22f00 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
22f10 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
22f20 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
22f30 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
22f40 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
22f50 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
22f60 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
22f70 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
22f80 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
22f90 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
22fa0 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
22fb0 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
22fc0 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
22fd0 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
22fe0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
22ff0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
23000 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
23010 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
23020 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
23030 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
23040 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
23050 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
23060 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
23070 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
23080 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
23090 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
230a0 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
230b0 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
230c0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
230d0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
230e0 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
230f0 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
23100 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
23110 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
23120 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
23130 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
23140 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
23150 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
23160 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
23170 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23180 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
23190 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
231a0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
231b0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
231c0 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
231d0 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
231e0 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
231f0 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
23200 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
23210 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
23220 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
23230 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
23240 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
23250 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
23260 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
23270 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
23280 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
23290 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
232a0 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
232b0 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
232c0 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
232d0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument 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 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
23300 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
23310 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
23320 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
23330 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
23340 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
23350 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
23360 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
23370 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
23380 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
23390 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
233a0 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
233b0 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
233c0 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
233d0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
233e0 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
233f0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
23400 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
23410 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
23420 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
23430 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
23440 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
23450 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
23460 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
23470 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
23480 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
23490 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
234a0 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
234b0 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
234c0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
234d0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
234e0 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
234f0 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
23500 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
23510 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
23520 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
23530 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
23540 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23550 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
23560 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
23570 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
23580 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
23590 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
235a0 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
235b0 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
235c0 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
235d0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
235e0 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
235f0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
23600 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
23610 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
23620 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
23630 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
23640 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
23650 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
23660 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
23670 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
23680 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
23690 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
236a0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
236b0 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
236c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
236d0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
236e0 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
236f0 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
23700 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
23710 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
23720 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
23730 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
23740 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
23750 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
23760 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
23770 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
23780 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
23790 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
237a0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
237b0 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
237c0 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
237d0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
237e0 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
237f0 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
23800 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
23810 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
23820 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
23830 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
23840 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
23850 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
23860 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
23870 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
23880 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
23890 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
238a0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
238b0 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
238c0 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
238d0 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
238e0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
238f0 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
23900 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
23910 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
23920 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
23930 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
23940 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
23950 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
23960 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
23970 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
23980 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
23990 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
239a0 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
239b0 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
239c0 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
239d0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
239e0 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
239f0 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
23a00 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23a10 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
23a20 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
23a30 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
23a40 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
23a50 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
23a60 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
23a70 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
23a80 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
23a90 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
23aa0 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
23ab0 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
23ac0 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
23ad0 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
23ae0 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
23af0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
23b00 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
23b10 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
23b20 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
23b30 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
23b40 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
23b50 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
23b60 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
23b70 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
23b80 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
23b90 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
23ba0 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
23bb0 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
23bc0 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
23bd0 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
23be0 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
23bf0 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
23c00 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
23c10 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
23c20 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
23c30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
23c40 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
23c50 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
23c60 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
23c70 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
23c80 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
23c90 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
23ca0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
23cb0 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
23cc0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
23cd0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
23ce0 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
23cf0 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
23d00 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
23d10 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
23d20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
23d30 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
23d40 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
23d50 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a  nix-nolock <td>.
23d60 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23d70 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
23d80 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
23d90 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
23da0 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a  "unix-nolock"..*
23db0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23dc0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
23dd0 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
23de0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
23df0 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
23e00 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
23e10 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
23e20 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
23e30 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
23e40 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
23e50 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
23e60 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
23e70 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
23e80 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
23e90 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
23ea0 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
23eb0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
23ec0 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
23ed0 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
23ee0 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
23ef0 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
23f00 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
23f10 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
23f20 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
23f30 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
23f40 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
23f50 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
23f60 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
23f70 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
23f80 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
23f90 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
23fa0 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
23fb0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
23fc0 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
23fd0 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
23fe0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
23ff0 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
24000 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
24010 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
24020 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
24030 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
24040 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
24050 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
24060 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
24070 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
24080 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
24090 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
240a0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
240b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
240c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
240d0 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
240e0 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
240f0 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
24100 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
24110 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
24120 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
24130 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
24140 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
24150 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
24160 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
24170 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
24180 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
24190 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
241a0 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ()..**.** <b>Not
241b0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
241c0 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
241d0 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
241e0 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
241f0 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
24200 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
24210 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
24220 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f  e3_open_v2().  O
24230 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
24240 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
24250 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
24260 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
24270 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a  files may fail..
24280 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
24290 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  [sqlite3_temp_di
242a0 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49  rectory].*/.SQLI
242b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
242c0 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
242d0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
242e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
242f0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
24300 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
24310 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
24320 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
24330 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49  andle */.);.SQLI
24340 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
24350 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
24360 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
24370 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
24380 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
24390 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
243a0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
243b0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
243c0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
243d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
243e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
243f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
24400 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
24410 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
24420 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
24430 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
24440 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
24450 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
24460 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
24470 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
24480 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
24490 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
244a0 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
244b0 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
244c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
244d0 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
244e0 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
244f0 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
24500 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
24510 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
24520 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
24530 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
24540 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
24550 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
24560 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
24570 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
24580 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
24590 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
245a0 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
245b0 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
245c0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
245d0 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74   If F is the dat
245e0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70  abase filename p
245f0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
24600 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d  to the xOpen() m
24610 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56  ethod of .** a V
24620 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
24630 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73  n when the flags
24640 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
24650 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72  pen() has one or
24660 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65   .** more of the
24670 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
24680 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  I] or [SQLITE_OP
24690 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73  EN_MAIN_DB] bits
246a0 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73   set and.** P is
246b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
246c0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
246d0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
246e0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
246f0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
24700 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
24710 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
24720 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
24730 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
24740 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
24750 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
24760 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
24770 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
24780 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
24790 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
247a0 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
247b0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
247c0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
247d0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
247e0 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
247f0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
24800 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
24810 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
24820 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
24830 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
24840 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
24850 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
24860 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
24870 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
24880 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
24890 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
248a0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
248b0 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ne returns true 
248c0 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61  (1) if the.** va
248d0 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72  lue of query par
248e0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
248f0 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22  of "yes", "true"
24900 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79  , or "on" in any
24910 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74  .** case or if t
24920 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
24930 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
24940 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a  number.  The .**
24950 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
24960 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
24970 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c  ines returns fal
24980 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61  se (0) if the va
24990 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20  lue of.** query 
249a0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
249b0 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c  ne of "no", "fal
249c0 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e  se", or "off" in
249d0 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20   any case or.** 
249e0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
249f0 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72  ins with a numer
24a00 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69  ic zero.  If P i
24a10 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a  s not a query.**
24a20 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20   parameter on F 
24a30 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
24a40 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74  of P is does not
24a50 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68   match any of th
24a60 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e  e.** above, then
24a70 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
24a80 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
24a90 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
24aa0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
24ab0 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
24ac0 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
24ad0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
24ae0 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
24af0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
24b00 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
24b10 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
24b20 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
24b30 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
24b40 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
24b50 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
24b60 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
24b70 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
24b80 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
24b90 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
24ba0 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
24bb0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
24bc0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
24bd0 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
24be0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
24bf0 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
24c00 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
24c10 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
24c20 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  ** is not a data
24c30 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61  base file pathna
24c40 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  me pointer that 
24c50 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e  SQLite passed in
24c60 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
24c70 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
24c80 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
24c90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
24ca0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
24cb0 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73  robably.** undes
24cc0 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54  irable..*/.SQLIT
24cd0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
24ce0 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
24cf0 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
24d00 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
24d10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
24d20 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  m);.SQLITE_API i
24d30 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
24d40 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
24d50 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
24d60 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
24d70 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c  t bDefault);.SQL
24d80 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
24d90 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
24da0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
24db0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
24dc0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
24dd0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
24de0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
24df0 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
24e00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
24e10 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
24e20 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
24e30 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
24e40 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
24e50 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
24e60 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
24e70 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
24e80 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
24e90 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
24ea0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
24eb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
24ec0 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
24ed0 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
24ee0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
24ef0 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
24f00 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
24f10 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
24f20 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
24f30 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
24f40 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
24f50 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
24f60 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
24f70 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
24f80 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
24f90 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
24fa0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
24fb0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
24fc0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
24fd0 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
24fe0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
24ff0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
25000 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
25010 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
25020 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
25030 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
25040 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
25050 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
25060 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
25070 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
25080 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
25090 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
250a0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
250b0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
250c0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
250d0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
250e0 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
250f0 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
25100 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
25110 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
25120 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
25130 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
25140 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
25150 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
25160 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
25170 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
25180 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
25190 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
251a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
251b0 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
251c0 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
251d0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
251e0 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
251f0 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
25200 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
25210 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
25220 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
25230 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
25240 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
25250 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
25260 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
25270 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
25280 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
25290 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
252a0 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
252b0 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
252c0 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
252d0 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
252e0 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
252f0 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
25300 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
25310 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
25320 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
25330 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
25340 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
25350 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
25360 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
25370 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
25380 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
25390 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
253a0 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
253b0 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
253c0 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
253d0 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
253e0 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
253f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
25400 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
25410 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
25420 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
25430 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
25440 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
25450 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
25460 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
25470 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
25480 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
25490 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
254a0 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
254b0 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
254c0 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
254d0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
254e0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
254f0 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
25500 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
25510 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
25520 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
25530 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
25540 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
25550 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
25560 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
25570 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
25580 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
25590 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
255a0 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
255b0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
255c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
255d0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
255e0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
255f0 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
25600 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
25610 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
25620 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
25630 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
25640 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
25650 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
25660 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
25670 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72   *sqlite3_errstr
25680 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
25690 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
256a0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
256b0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
256c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
256d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
256e0 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
256f0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
25700 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
25710 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
25720 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73  atement..** This
25730 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f   object is vario
25740 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
25750 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
25760 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f  ent" or a.** "co
25770 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
25780 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20  ment" or simply 
25790 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22  as a "statement"
257a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
257b0 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20   of a statement 
257c0 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65  object goes some
257d0 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a  thing like this:
257e0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
257f0 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f  li> Create the o
25800 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
25810 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
25820 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a  )] or a related.
25830 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e  **      function
25840 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
25850 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70  alues to [host p
25860 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
25870 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
25880 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
25890 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
258a0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
258b0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
258c0 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
258d0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
258e0 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
258f0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
25900 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
25910 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
25920 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
25930 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
25940 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
25950 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
25960 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
25970 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25980 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
25990 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
259a0 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
259b0 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
259c0 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
259d0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
259e0 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
259f0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
25a00 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
25a10 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
25a20 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
25a30 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  its.**.** ^(This
25a40 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
25a50 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
25a60 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
25a70 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
25a80 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
25a90 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
25aa0 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
25ab0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
25ac0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
25ad0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
25ae0 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
25af0 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
25b00 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
25b10 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
25b20 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
25b30 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
25b40 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
25b50 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
25b60 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
25b70 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
25b80 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
25b90 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
25ba0 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
25bb0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
25bc0 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
25bd0 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
25be0 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
25bf0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f  changed..** ^(Fo
25c00 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74  r each limit cat
25c10 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d  egory SQLITE_LIM
25c20 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74  IT_<i>NAME</i> t
25c30 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c  here is a .** [l
25c40 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70  imits | hard upp
25c50 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74  er bound].** set
25c60 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
25c70 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65   by a C preproce
25c80 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65  ssor macro calle
25c90 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53  d.** [limits | S
25ca0 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d  QLITE_MAX_<i>NAM
25cb0 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20  E</i>]..** (The 
25cc0 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
25cd0 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
25ce0 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a   to "_MAX_".))^.
25cf0 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20  ** ^Attempts to 
25d00 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
25d10 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
25d20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
25d30 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
25d40 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
25d50 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a  d upper bound..*
25d60 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73  *.** ^Regardless
25d70 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
25d80 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73  ot the limit was
25d90 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a   changed, the .*
25da0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  * [sqlite3_limit
25db0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
25dc0 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20  turns the prior 
25dd0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
25de0 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74  it..** ^Hence, t
25df0 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65  o find the curre
25e00 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69  nt value of a li
25e10 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e  mit without chan
25e20 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70  ging it,.** simp
25e30 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69  ly invoke this i
25e40 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68  nterface with th
25e50 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
25e60 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a  r set to -1..**.
25e70 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ** Run-time limi
25e80 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
25e90 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
25ea0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
25eb0 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
25ec0 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
25ed0 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
25ee0 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
25ef0 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
25f00 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
25f10 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
25f20 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
25f30 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
25f40 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
25f50 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
25f60 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
25f70 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
25f80 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
25f90 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
25fa0 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
25fb0 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
25fc0 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
25fd0 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
25fe0 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
25ff0 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
26000 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
26010 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
26020 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
26030 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
26040 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
26050 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
26060 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
26070 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
26080 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
26090 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
260a0 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
260b0 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
260c0 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
260d0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
260e0 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
260f0 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
26100 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
26110 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
26120 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
26130 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
26140 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
26150 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
26160 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
26170 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
26180 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
26190 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
261a0 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
261b0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
261c0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f  ure releases..*/
261d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
261e0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
261f0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
26200 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
26210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
26220 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
26230 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
26240 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
26250 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
26260 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
26270 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
26280 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
26290 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
262a0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
262b0 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
262c0 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
262d0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
262e0 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
262f0 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
26300 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
26310 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
26320 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
26330 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
26340 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
26350 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
26360 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
26370 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
26380 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
26390 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
263a0 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
263b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
263c0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
263d0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
263e0 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
263f0 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
26400 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26410 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
26420 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26430 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
26440 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26450 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
26460 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
26470 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
26480 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26490 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
264a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
264b0 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
264c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
264d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
264e0 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
264f0 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
26500 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
26510 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
26520 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
26530 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
26540 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
26550 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
26560 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
26570 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
26580 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26590 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
265a0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
265b0 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
265c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
265d0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
265e0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
265f0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
26600 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26610 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
26620 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
26630 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26640 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
26650 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26660 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
26670 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
26680 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
26690 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
266a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
266b0 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
266c0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
266d0 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
266e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
266f0 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
26700 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
26710 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
26720 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
26730 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
26740 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
26750 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
26760 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
26770 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
26780 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
26790 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
267a0 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
267b0 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
267c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
267d0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
267e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
267f0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
26800 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26810 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
26820 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
26830 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
26840 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
26850 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
26860 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26870 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
26880 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26890 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
268a0 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
268b0 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
268c0 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
268d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
268e0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
268f0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
26900 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
26910 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
26920 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26930 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
26940 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
26950 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
26960 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
26970 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
26980 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26990 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
269a0 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
269b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
269c0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
269d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
269e0 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
269f0 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
26a00 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
26a10 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
26a20 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26a30 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
26a40 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26a50 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
26a60 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
26a70 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
26a80 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
26a90 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
26aa0 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
26ab0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26ac0 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
26ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
26ae0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26af0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
26b00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
26b10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26b20 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
26b30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
26b40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26b50 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
26b60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26b70 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
26b80 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
26b90 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
26ba0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
26bb0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
26bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26bd0 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
26be0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
26bf0 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
26c00 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
26c10 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
26c20 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
26c30 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
26c40 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
26c50 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
26c60 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
26c70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
26c80 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
26c90 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
26ca0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
26cb0 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
26cc0 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20        10../*.** 
26cd0 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
26ce0 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
26cf0 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
26d00 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
26d10 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a   compiler}.**.**
26d20 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
26d30 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
26d40 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
26d50 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
26d60 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
26d70 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
26d80 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
26d90 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
26da0 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
26db0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
26dc0 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
26dd0 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
26de0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
26df0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
26e00 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
26e10 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
26e20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
26e30 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
26e40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
26e50 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
26e60 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
26e70 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
26e80 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
26e90 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
26ea0 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
26eb0 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
26ec0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
26ed0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
26ee0 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
26ef0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26f00 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
26f10 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
26f20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26f30 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
26f40 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
26f50 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
26f60 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
26f70 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
26f80 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
26f90 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
26fa0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
26fb0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
26fc0 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
26fd0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
26fe0 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
26ff0 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  imum.** number o
27000 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72  f  bytes read fr
27010 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20  om zSql.  ^When 
27020 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
27030 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
27040 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
27050 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
27060 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
27070 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
27080 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
27090 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
270a0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
270b0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
270c0 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
270d0 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
270e0 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
270f0 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
27100 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
27110 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
27120 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
27130 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
27140 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
27150 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
27160 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
27170 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
27180 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
27190 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
271a0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
271b0 62 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61  bytes as this sa
271c0 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20  ves SQLite from 
271d0 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b  having to.** mak
271e0 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  e a copy of the 
271f0 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a  input string..**
27200 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
27210 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
27220 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
27230 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
27240 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
27250 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
27260 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
27270 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
27280 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
27290 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
272a0 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
272b0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
272c0 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
272d0 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
272e0 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
272f0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
27300 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
27310 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
27320 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
27330 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
27340 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
27350 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
27360 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
27370 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
27380 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
27390 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
273a0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
273b0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
273c0 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
273d0 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
273e0 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
273f0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
27400 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
27410 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
27420 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
27430 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
27440 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
27450 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
27460 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
27470 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
27480 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
27490 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
274a0 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
274b0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
274c0 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
274d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
274e0 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
274f0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
27500 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
27510 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
27520 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
27530 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
27540 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27550 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
27560 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
27570 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
27580 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
27590 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
275a0 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
275b0 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
275c0 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
275d0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
275e0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
275f0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
27600 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
27610 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
27620 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
27630 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
27640 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
27650 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
27660 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
27670 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
27680 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
27690 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
276a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
276b0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
276c0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
276d0 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
276e0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
276f0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
27700 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
27710 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
27720 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
27730 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
27740 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
27750 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
27760 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27770 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
27780 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
27790 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
277a0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
277b0 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
277c0 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
277d0 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
277e0 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
277f0 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
27800 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
27810 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
27820 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
27830 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
27840 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
27850 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
27860 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
27870 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
27880 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
27890 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
278a0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
278b0 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
278c0 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
278d0 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
278e0 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
278f0 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
27900 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
27910 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
27920 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
27930 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
27940 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
27950 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
27960 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
27970 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
27980 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
27990 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
279a0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
279b0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
279c0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
279d0 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
279e0 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
279f0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
27a00 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
27a10 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
27a20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
27a30 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
27a40 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
27a50 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
27a60 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
27a70 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
27a80 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
27a90 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
27aa0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
27ab0 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
27ac0 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
27ad0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
27ae0 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
27af0 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
27b00 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
27b10 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
27b20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
27b30 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
27b40 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
27b50 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
27b60 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
27b70 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
27b80 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
27b90 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
27ba0 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
27bb0 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
27bc0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
27bd0 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
27be0 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
27bf0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
27c00 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
27c10 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
27c20 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
27c30 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
27c40 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
27c50 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
27c60 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
27c70 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
27c80 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
27c90 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
27ca0 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
27cb0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ol>.*/.SQLI
27cc0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27cd0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
27ce0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
27cf0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
27d00 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
27d10 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
27d20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
27d30 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
27d40 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
27d50 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
27d60 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
27d70 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
27d80 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
27d90 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
27da0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
27db0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
27dc0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
27dd0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
27de0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
27df0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
27e00 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
27e10 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27e20 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
27e30 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
27e40 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
27e50 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
27e60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
27e70 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
27e80 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
27e90 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
27ea0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
27eb0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
27ec0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
27ed0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
27ee0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
27ef0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
27f00 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
27f10 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
27f20 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
27f30 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
27f40 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
27f50 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
27f60 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
27f70 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
27f80 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
27f90 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
27fa0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
27fb0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
27fc0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
27fd0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
27fe0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
27ff0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
28000 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
28010 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
28020 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
28030 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
28040 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
28050 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
28060 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
28070 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
28080 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
28090 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
280a0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
280b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
280c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
280d0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
280e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
280f0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
28100 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
28110 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
28120 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
28130 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
28140 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
28150 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
28160 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
28170 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
28180 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
28190 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
281a0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
281b0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
281c0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
281d0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
281e0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
281f0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
28200 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28210 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
28220 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
28230 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
28240 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
28250 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
28260 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
28270 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
28280 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
28290 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
282a0 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
282b0 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
282c0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
282d0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
282e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
282f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28300 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  16_v2()]..*/.SQL
28310 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
28320 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
28330 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
28340 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
28350 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
28360 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
28370 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
28380 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
28390 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
283a0 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
283b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
283c0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
283d0 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
283e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
283f0 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
28400 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
28410 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
28420 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
28430 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
28440 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
28450 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28460 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
28470 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
28480 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
28490 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
284a0 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
284b0 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
284c0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
284d0 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
284e0 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
284f0 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
28500 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
28510 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
28520 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
28530 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
28540 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
28550 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
28560 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
28570 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
28580 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
28590 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
285a0 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
285b0 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
285c0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
285d0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
285e0 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
285f0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
28600 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
28610 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28620 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
28630 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
28640 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
28650 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
28660 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
28670 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
28680 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
28690 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
286a0 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
286b0 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
286c0 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
286d0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
286e0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
286f0 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
28700 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
28710 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
28720 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
28730 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
28740 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
28750 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
28760 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
28770 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
28780 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
28790 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
287a0 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
287b0 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
287c0 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
287d0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
287e0 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
287f0 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
28800 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
28810 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
28820 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
28830 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
28840 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
28850 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
28860 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
28870 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
28880 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
28890 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  sk..*/.SQLITE_AP
288a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
288b0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
288c0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
288d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
288e0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
288f0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
28900 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
28910 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
28920 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
28930 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
28940 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
28950 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
28960 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28970 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
28980 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
28990 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
289a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
289b0 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75  ] but has not ru
289c0 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
289d0 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a  and/or has not .
289e0 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
289f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
28a00 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
28a10 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
28a20 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
28a30 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
28a40 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
28a50 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
28a60 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
28a70 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
28a80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
28a90 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
28aa0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
28ab0 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
28ac0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
28ad0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
28ae0 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
28af0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
28b00 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
28b10 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
28b20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
28b30 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
28b40 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
28b50 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
28b60 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
28b70 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
28b80 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
28b90 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
28ba0 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
28bb0 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
28bc0 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
28bd0 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
28be0 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
28bf0 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
28c00 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
28c10 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
28c20 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c  ion open..*/.SQL
28c30 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28c40 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71  te3_stmt_busy(sq
28c50 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
28c60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28c70 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
28c80 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
28c90 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
28ca0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28cb0 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
28cc0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
28cd0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
28ce0 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
28cf0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
28d00 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
28d10 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
28d20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
28d30 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
28d40 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
28d50 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
28d60 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
28d70 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
28d80 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
28d90 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
28da0 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
28db0 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
28dc0 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
28dd0 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
28de0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
28df0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28e00 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
28e10 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
28e20 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
28e30 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
28e40 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
28e50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28e60 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
28e70 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
28e80 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
28e90 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
28ea0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28eb0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
28ec0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
28ed0 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
28ee0 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
28ef0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
28f00 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
28f10 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
28f20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28f30 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
28f40 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
28f50 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
28f60 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
28f70 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
28f80 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
28f90 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
28fa0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
28fb0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
28fc0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28fd0 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
28fe0 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
28ff0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
29000 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29010 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
29020 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
29030 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
29040 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
29050 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
29060 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
29070 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
29080 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
29090 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
290a0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
290b0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
290c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
290d0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
290e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
290f0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
29100 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
29110 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
29120 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
29130 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
29140 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
29150 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
29160 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
29170 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
29180 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
29190 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
291a0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
291b0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
291c0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
291d0 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
291e0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
291f0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
29200 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
29210 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
29220 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
29230 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
29240 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
29250 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
29260 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
29270 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
29280 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
29290 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
292a0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
292b0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
292c0 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
292d0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
292e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
292f0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
29300 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
29310 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
29320 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
29330 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
29340 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29350 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
29360 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
29370 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
29380 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
29390 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
293a0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
293b0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
293c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
293d0 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
293e0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
293f0 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
29400 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29410 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
29420 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
29430 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
29440 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
29450 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
29460 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
29470 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
29480 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
29490 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
294a0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
294b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
294c0 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
294d0 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
294e0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
294f0 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
29500 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
29510 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29520 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
29530 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
29540 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
29550 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
29560 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
29570 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
29580 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
29590 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
295a0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
295b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
295c0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
295d0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
295e0 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
295f0 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
29600 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
29610 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
29620 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
29630 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
29640 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
29650 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
29660 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
29670 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
29680 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
29690 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
296a0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
296b0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
296c0 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
296d0 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
296e0 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
296f0 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
29700 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
29710 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
29720 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
29730 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
29740 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a  ter binding}.**.
29750 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
29760 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
29770 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
29780 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
29790 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
297a0 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
297b0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
297c0 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
297d0 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
297e0 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
297f0 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
29800 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
29810 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
29820 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
29830 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
29840 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
29850 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
29860 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
29870 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
29880 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
29890 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
298a0 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
298b0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
298c0 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
298d0 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
298e0 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
298f0 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
29900 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
29910 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
29920 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
29930 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
29940 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
29950 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
29960 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
29970 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
29980 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
29990 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
299a0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
299b0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
299c0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
299d0 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
299e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
299f0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
29a00 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
29a10 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
29a20 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
29a30 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
29a40 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
29a50 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
29a60 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
29a70 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
29a80 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
29a90 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
29aa0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
29ab0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
29ac0 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
29ad0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
29ae0 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
29af0 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
29b00 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
29b10 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
29b20 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
29b30 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
29b40 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
29b50 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
29b60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
29b70 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
29b80 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
29b90 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
29ba0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
29bb0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
29bc0 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
29bd0 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
29be0 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
29bf0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
29c00 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
29c10 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
29c20 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
29c30 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
29c40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
29c50 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
29c60 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
29c70 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
29c80 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
29c90 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
29ca0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29cb0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
29cc0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
29cd0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
29ce0 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c  _blob() is a NUL
29cf0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
29d00 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
29d10 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65  ter.** is ignore
29d20 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65  d and the end re
29d30 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65  sult is the same
29d40 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   as sqlite3_bind
29d50 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  _null()..**.** ^
29d60 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
29d70 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
29d80 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
29d90 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
29da0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
29db0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
29dc0 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
29dd0 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
29de0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
29df0 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
29e00 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
29e10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
29e20 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
29e30 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
29e40 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
29e50 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
29e60 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
29e70 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e  text16().** is n
29e80 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
29e90 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
29ea0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
29eb0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
29ec0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
29ed0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
29ee0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
29ef0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
29f00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29f10 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c  b() is negative,
29f20 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68   then.** the beh
29f30 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
29f40 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d  ed..** If a non-
29f50 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20  negative fourth 
29f60 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f  parameter is pro
29f70 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33  vided to sqlite3
29f80 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20  _bind_text().** 
29f90 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
29fa0 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68  text16() then th
29fb0 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
29fc0 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
29fd0 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
29fe0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
29ff0 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
2a000 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
2a010 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
2a020 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
2a030 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
2a040 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
2a050 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
2a060 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
2a070 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2a080 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
2a090 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
2a0a0 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
2a0b0 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
2a0c0 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
2a0d0 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
2a0e0 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
2a0f0 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
2a100 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
2a110 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2a120 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2a130 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2a140 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2a150 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
2a160 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
2a170 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
2a180 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
2a190 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2a1a0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
2a1b0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
2a1c0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2a1d0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
2a1e0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
2a1f0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
2a200 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
2a210 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
2a220 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2a230 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  _bind_blob(),.**
2a240 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a250 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  xt(), or sqlite3
2a260 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66  _bind_text16() f
2a270 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74  ails.  .** ^If t
2a280 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2a290 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
2a2a0 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
2a2b0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
2a2c0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
2a2d0 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
2a2e0 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
2a2f0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
2a300 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
2a310 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
2a320 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
2a330 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
2a340 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
2a350 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
2a360 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
2a370 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
2a380 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
2a390 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
2a3a0 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
2a3b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2a3c0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2a3d0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
2a3e0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2a3f0 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
2a400 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
2a410 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
2a420 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
2a430 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
2a440 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
2a450 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
2a460 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
2a470 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
2a480 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
2a490 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
2a4a0 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
2a4b0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
2a4c0 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
2a4d0 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
2a4e0 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
2a4f0 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
2a500 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
2a510 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
2a520 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
2a530 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
2a540 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
2a550 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
2a560 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
2a570 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
2a580 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
2a590 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
2a5a0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2a5b0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2a5c0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
2a5d0 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
2a5e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a5f0 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
2a600 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a610 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
2a620 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2a630 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
2a640 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
2a650 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2a660 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
2a670 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
2a680 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2a690 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
2a6a0 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
2a6b0 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
2a6c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2a6d0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
2a6e0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
2a6f0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
2a700 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2a710 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
2a720 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
2a730 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
2a740 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
2a750 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
2a760 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
2a770 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
2a780 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
2a790 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
2a7a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
2a7b0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2a7c0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
2a7d0 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
2a7e0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
2a7f0 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
2a800 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2a810 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2a820 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2a830 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2a840 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2a850 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2a860 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2a870 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2a880 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2a890 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a8a0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2a8b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2a8c0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2a8d0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
2a8e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2a8f0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2a900 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2a910 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
2a920 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2a930 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2a940 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
2a950 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2a960 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a970 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2a980 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
2a990 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  le);.SQLITE_API 
2a9a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a9b0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2a9c0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53  t*, int, int);.S
2a9d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2a9e0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
2a9f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2aa00 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
2aa10 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
2aa20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2aa30 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
2aa40 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  mt*, int);.SQLIT
2aa50 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2aa60 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
2aa70 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2aa80 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2aa90 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
2aaa0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2aab0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2aac0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2aad0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2aae0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2aaf0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2ab00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2ab10 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2ab20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ab30 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
2ab40 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2ab50 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2ab60 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2ab70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ab80 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
2ab90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2aba0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2abb0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
2abc0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2abd0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
2abe0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
2abf0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
2ac00 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
2ac10 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
2ac20 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2ac30 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2ac40 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2ac50 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2ac60 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2ac70 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2ac80 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2ac90 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2aca0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2acb0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2acc0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2acd0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2ace0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2acf0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2ad00 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2ad10 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2ad20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2ad30 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2ad40 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2ad50 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2ad60 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2ad70 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2ad80 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2ad90 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2ada0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2adb0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2adc0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2add0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2ade0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2adf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ae00 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2ae10 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2ae20 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2ae30 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2ae40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ae50 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2ae60 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2ae70 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2ae80 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
2ae90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2aea0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2aeb0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
2aec0 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e  arameter.**.** ^
2aed0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2aee0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2aef0 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
2af00 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
2af10 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
2af20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
2af30 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2af40 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2af50 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
2af60 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2af70 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2af80 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2af90 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
2afa0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
2afb0 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
2afc0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2afd0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
2afe0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
2aff0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2b000 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
2b010 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
2b020 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
2b030 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
2b040 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
2b050 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2b060 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
2b070 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
2b080 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
2b090 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
2b0a0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
2b0b0 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
2b0c0 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
2b0d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2b0e0 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
2b0f0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2b100 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
2b110 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
2b120 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
2b130 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
2b140 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
2b150 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
2b160 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
2b170 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2b180 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
2b190 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
2b1a0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
2b1b0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
2b1c0 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
2b1d0 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
2b1e0 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
2b1f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2b200 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2b210 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2b220 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2b230 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2b240 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2b250 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2b260 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2b270 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2b280 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b290 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2b2a0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2b2b0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2b2c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2b2d0 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
2b2e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
2b2f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b300 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
2b310 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
2b320 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65  n Name.**.** ^Re
2b330 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
2b340 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
2b350 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
2b360 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
2b370 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
2b380 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
2b390 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
2b3a0 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
2b3b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
2b3c0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2b3d0 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
2b3e0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
2b3f0 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
2b400 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
2b410 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
2b420 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
2b430 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
2b440 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
2b450 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
2b460 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
2b470 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
2b480 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2b490 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2b4a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2b4b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2b4c0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2b4d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2b4e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2b4f0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2b500 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2b510 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2b520 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2b530 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2b540 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2b550 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
2b560 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2b570 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
2b580 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
2b590 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
2b5a0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2b5b0 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
2b5c0 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
2b5d0 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
2b5e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
2b5f0 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
2b600 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2b610 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
2b620 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
2b630 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2b640 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
2b650 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
2b660 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
2b670 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54  o NULL..*/.SQLIT
2b680 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2b690 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2b6a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2b6b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b6c0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
2b6d0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
2b6e0 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  Set.**.** ^Retur
2b6f0 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
2b700 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2b710 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
2b720 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
2b730 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b740 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
2b750 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
2b760 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
2b770 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
2b780 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
2b790 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
2b7a0 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
2b7b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2b7c0 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
2b7d0 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
2b7e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b7f0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
2b800 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b810 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b820 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
2b830 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2b840 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2b850 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2b860 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
2b870 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
2b880 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
2b890 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2b8a0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2b8b0 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
2b8c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2b8d0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2b8e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2b8f0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2b900 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
2b910 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
2b920 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2b930 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
2b940 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2b950 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
2b960 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2b970 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2b980 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
2b990 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2b9a0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2b9b0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2b9c0 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
2b9d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2b9e0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
2b9f0 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
2ba00 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
2ba10 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
2ba20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2ba30 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
2ba40 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
2ba50 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
2ba60 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
2ba70 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
2ba80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ba90 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2baa0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2bab0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2bac0 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2bad0 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2bae0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2baf0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2bb00 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2bb10 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2bb20 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2bb30 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
2bb40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2bb50 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
2bb60 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
2bb70 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
2bb80 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
2bb90 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
2bba0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
2bbb0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
2bbc0 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
2bbd0 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
2bbe0 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
2bbf0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
2bc00 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2bc10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2bc20 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
2bc30 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
2bc40 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
2bc50 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
2bc60 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
2bc70 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
2bc80 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
2bc90 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
2bca0 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
2bcb0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
2bcc0 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
2bcd0 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
2bce0 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
2bcf0 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
2bd00 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  xt..*/.SQLITE_AP
2bd10 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2bd20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2bd30 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2bd40 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
2bd50 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2bd60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2bd70 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2bd80 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
2bd90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
2bda0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
2bdb0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2bdc0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2bdd0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
2bde0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
2bdf0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
2be00 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
2be10 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
2be20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
2be30 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
2be40 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
2be50 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
2be60 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
2be70 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2be80 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
2be90 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
2bea0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
2beb0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
2bec0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2bed0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
2bee0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
2bef0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
2bf00 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
2bf10 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2bf20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
2bf30 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
2bf40 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
2bf50 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
2bf60 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
2bf70 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
2bf80 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
2bf90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bfa0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
2bfb0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2bfc0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2bfd0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2bfe0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2bff0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2c000 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2c010 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2c020 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2c030 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2c040 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2c050 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
2c060 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
2c070 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
2c080 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
2c090 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
2c0a0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
2c0b0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
2c0c0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
2c0d0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
2c0e0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
2c0f0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
2c100 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2c110 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
2c120 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2c130 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2c140 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2c150 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2c160 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
2c170 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
2c180 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
2c190 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
2c1a0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
2c1b0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
2c1c0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
2c1d0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
2c1e0 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
2c1f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
2c200 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
2c210 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2c220 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
2c230 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
2c240 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
2c250 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
2c260 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
2c270 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
2c280 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
2c290 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
2c2a0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
2c2b0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
2c2c0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2c2d0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
2c2e0 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
2c2f0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
2c300 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2c310 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2c320 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
2c330 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
2c340 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
2c350 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
2c360 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
2c370 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
2c380 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
2c390 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
2c3a0 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
2c3b0 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
2c3c0 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
2c3d0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
2c3e0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
2c3f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
2c400 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
2c410 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2c420 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2c430 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2c440 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2c450 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2c460 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2c470 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
2c480 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2c490 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2c4a0 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
2c4b0 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
2c4c0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
2c4d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
2c4e0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
2c4f0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2c500 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
2c510 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2c520 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2c530 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2c540 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
2c550 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2c560 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
2c570 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
2c580 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
2c590 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
2c5a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
2c5b0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
2c5c0 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
2c5d0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2c5e0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2c5f0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
2c600 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2c610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2c620 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
2c630 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2c640 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2c650 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c660 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2c670 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2c680 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2c690 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2c6a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c6b0 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2c6c0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2c6d0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2c6e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2c6f0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
2c700 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2c710 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2c720 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2c730 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2c740 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2c750 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2c760 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2c770 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c780 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
2c790 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2c7a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c7b0 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
2c7c0 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
2c7d0 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
2c7e0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2c7f0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
2c800 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2c810 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
2c820 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
2c830 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
2c840 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2c850 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
2c860 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
2c870 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
2c880 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
2c890 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
2c8a0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2c8b0 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
2c8c0 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
2c8d0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
2c8e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
2c8f0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2c900 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2c910 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
2c920 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2c930 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
2c940 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2c950 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
2c960 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2c970 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
2c980 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
2c990 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
2c9a0 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
2c9b0 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
2c9c0 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
2c9d0 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
2c9e0 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
2c9f0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
2ca00 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
2ca10 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
2ca20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
2ca30 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
2ca40 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
2ca50 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
2ca60 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
2ca70 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
2ca80 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
2ca90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
2caa0 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
2cab0 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
2cac0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
2cad0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2cae0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
2caf0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
2cb00 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
2cb10 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
2cb20 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
2cb30 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
2cb40 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
2cb50 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
2cb60 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
2cb70 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
2cb80 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
2cb90 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
2cba0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
2cbb0 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
2cbc0 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
2cbd0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
2cbe0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
2cbf0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
2cc00 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
2cc10 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
2cc20 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
2cc30 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2cc40 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2cc50 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2cc60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2cc70 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2cc80 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2cc90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2cca0 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
2ccb0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2ccc0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
2ccd0 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
2cce0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
2ccf0 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
2cd00 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
2cd10 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
2cd20 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
2cd30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2cd40 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2cd50 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2cd60 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
2cd70 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
2cd80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2cd90 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
2cda0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
2cdb0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
2cdc0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
2cdd0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
2cde0 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
2cdf0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
2ce00 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
2ce10 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2ce20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2ce30 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
2ce40 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
2ce50 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
2ce60 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
2ce70 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
2ce80 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
2ce90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2cea0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2ceb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2cec0 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
2ced0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2cee0 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
2cef0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2cf00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2cf10 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
2cf20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
2cf30 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2cf40 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
2cf50 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
2cf60 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
2cf70 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
2cf80 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
2cf90 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
2cfa0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2cfb0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
2cfc0 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
2cfd0 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
2cfe0 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
2cff0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
2d000 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
2d010 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
2d020 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
2d030 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
2d040 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
2d050 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
2d060 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
2d070 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
2d080 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
2d090 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
2d0a0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2d0b0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
2d0c0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
2d0d0 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
2d0e0 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
2d0f0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
2d100 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
2d110 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
2d120 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2d130 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
2d140 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
2d150 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
2d160 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
2d170 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
2d180 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
2d190 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
2d1a0 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
2d1b0 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
2d1c0 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
2d1d0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2d1e0 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
2d1f0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
2d200 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
2d210 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
2d220 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2d230 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
2d240 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2d250 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
2d260 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
2d270 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
2d280 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2d290 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2d2a0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
2d2b0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
2d2c0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
2d2d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2d2e0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
2d2f0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
2d300 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
2d310 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
2d320 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
2d330 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
2d340 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
2d350 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
2d360 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
2d370 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
2d380 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
2d390 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
2d3a0 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
2d3b0 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
2d3c0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
2d3d0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
2d3e0 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
2d3f0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2d400 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
2d410 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
2d420 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
2d430 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
2d440 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
2d450 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
2d460 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
2d470 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
2d480 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
2d490 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
2d4a0 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
2d4b0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2d4c0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2d4d0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
2d4e0 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
2d4f0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
2d500 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
2d510 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
2d520 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
2d530 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2d540 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
2d550 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
2d560 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
2d570 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
2d580 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
2d590 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
2d5a0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
2d5b0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
2d5c0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
2d5d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d5e0 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
2d5f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d600 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
2d610 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
2d620 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2d630 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
2d640 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
2d650 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2d660 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
2d670 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
2d680 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
2d690 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
2d6a0 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
2d6b0 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
2d6c0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
2d6d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d6e0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
2d6f0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
2d700 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
2d710 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
2d720 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
2d730 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
2d740 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
2d750 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
2d760 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
2d770 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
2d780 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
2d790 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d7a0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
2d7b0 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
2d7c0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
2d7d0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
2d7e0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
2d7f0 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
2d800 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
2d810 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
2d820 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
2d830 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
2d840 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
2d850 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
2d860 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
2d870 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
2d880 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2d890 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
2d8a0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
2d8b0 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
2d8c0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
2d8d0 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
2d8e0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2d8f0 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
2d900 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d910 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
2d920 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
2d930 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
2d940 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2d950 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76  ().  But after v
2d960 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
2d970 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2d980 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
2d990 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d9a0 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
2d9b0 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
2d9c0 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
2d9d0 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
2d9e0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2d9f0 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
2da00 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
2da10 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
2da20 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
2da30 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
2da40 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
2da50 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
2da60 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
2da70 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
2da80 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
2da90 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
2daa0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
2dab0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
2dac0 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
2dad0 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
2dae0 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
2daf0 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
2db00 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
2db10 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
2db20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
2db30 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
2db40 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
2db50 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
2db60 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
2db70 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
2db80 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
2db90 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
2dba0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2dbb0 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
2dbc0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2dbd0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2dbe0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
2dbf0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
2dc00 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
2dc10 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2dc20 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
2dc30 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
2dc40 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
2dc50 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
2dc60 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
2dc70 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
2dc80 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
2dc90 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2dca0 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
2dcb0 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
2dcc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
2dcd0 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
2dce0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2dcf0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2dd00 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2dd10 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
2dd20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
2dd30 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2dd40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2dd50 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
2dd60 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
2dd70 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
2dd80 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
2dd90 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
2dda0 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
2ddb0 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
2ddc0 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
2ddd0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2dde0 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  mended..*/.SQLIT
2ddf0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2de00 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2de10 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2de20 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2de30 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2de40 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
2de50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2de60 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
2de70 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2de80 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2de90 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
2dea0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2deb0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
2dec0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ded0 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
2dee0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2def0 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
2df00 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
2df10 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
2df20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
2df30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2df40 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
2df50 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
2df60 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
2df70 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2df80 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
2df90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2dfa0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2dfb0 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
2dfc0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
2dfd0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
2dfe0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2dff0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2e000 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
2e010 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2e020 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2e030 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2e040 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
2e050 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
2e060 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
2e070 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
2e080 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
2e090 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2e0a0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2e0b0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
2e0c0 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
2e0d0 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
2e0e0 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
2e0f0 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
2e100 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
2e110 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
2e120 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
2e130 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
2e140 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
2e150 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
2e160 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
2e170 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
2e180 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  mn_count()].*/.S
2e190 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2e1a0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2e1b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2e1c0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2e1d0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
2e1e0 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
2e1f0 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
2e200 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
2e210 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
2e220 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
2e230 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
2e240 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
2e250 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
2e260 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2e270 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
2e280 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
2e290 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
2e2a0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
2e2b0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
2e2c0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
2e2d0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
2e2e0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
2e2f0 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
2e300 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
2e310 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
2e320 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
2e330 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
2e340 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
2e350 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
2e360 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
2e370 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
2e380 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
2e390 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
2e3a0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
2e3b0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
2e3c0 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
2e3d0 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
2e3e0 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
2e3f0 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
2e400 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
2e410 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2e420 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
2e430 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
2e440 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
2e450 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
2e460 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
2e470 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
2e480 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
2e490 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
2e4a0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
2e4b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
2e4c0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
2e4d0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
2e4e0 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
2e4f0 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
2e500 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
2e510 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
2e520 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2e530 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
2e540 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61  ult set" interfa
2e550 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ce..**.** ^These
2e560 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2e570 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2e580 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
2e590 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
2e5a0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
2e5b0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
2e5c0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
2e5d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
2e5e0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
2e5f0 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
2e600 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2e610 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
2e620 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2e630 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
2e640 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
2e650 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
2e660 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
2e670 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
2e680 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
2e690 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2e6a0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2e6b0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
2e6c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
2e6d0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
2e6e0 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
2e6f0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
2e700 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
2e710 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
2e720 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
2e730 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2e740 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
2e750 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
2e760 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2e770 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
2e780 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2e790 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
2e7a0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
2e7b0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
2e7c0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
2e7d0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2e7e0 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
2e7f0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
2e800 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2e810 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
2e820 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
2e830 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2e840 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2e850 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2e860 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2e870 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
2e880 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e890 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
2e8a0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
2e8b0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
2e8c0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
2e8d0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2e8e0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2e8f0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2e900 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2e910 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e920 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
2e930 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2e940 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
2e950 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
2e960 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
2e970 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2e980 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
2e990 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2e9a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2e9b0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2e9c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
2e9d0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
2e9e0 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
2e9f0 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
2ea00 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2ea10 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
2ea20 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
2ea30 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2ea40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2ea50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2ea60 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2ea70 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
2ea80 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
2ea90 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
2eaa0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
2eab0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
2eac0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
2ead0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
2eae0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
2eaf0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
2eb00 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
2eb10 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
2eb20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
2eb30 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
2eb40 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
2eb50 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2eb60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2eb70 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
2eb80 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
2eb90 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
2eba0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
2ebb0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
2ebc0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
2ebd0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
2ebe0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2ebf0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2ec00 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
2ec10 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
2ec20 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
2ec30 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
2ec40 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2ec50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ec60 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
2ec70 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
2ec80 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
2ec90 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2eca0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
2ecb0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2ecc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ecd0 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
2ece0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2ecf0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2ed00 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2ed10 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2ed20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2ed30 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
2ed40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ed50 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
2ed60 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2ed70 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
2ed80 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2ed90 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2eda0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2edb0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2edc0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2edd0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
2ede0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2edf0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2ee00 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2ee10 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
2ee20 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2ee30 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2ee40 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2ee50 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2ee60 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2ee70 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2ee80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
2ee90 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2eea0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2eeb0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2eec0 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
2eed0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2eee0 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
2eef0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2ef00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2ef10 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2ef20 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2ef30 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2ef40 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
2ef50 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2ef60 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
2ef70 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2ef80 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
2ef90 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2efa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2efb0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2efc0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2efd0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2efe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2eff0 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
2f000 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2f010 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2f020 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2f030 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
2f040 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2f050 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2f060 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2f070 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2f080 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2f090 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2f0a0 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
2f0b0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2f0c0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
2f0d0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2f0e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2f0f0 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2f100 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2f110 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
2f120 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
2f130 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
2f140 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
2f150 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
2f160 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
2f170 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2f180 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f190 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
2f1a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2f1b0 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
2f1c0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
2f1d0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
2f1e0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2f1f0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
2f200 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
2f210 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2f220 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
2f230 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2f240 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
2f250 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
2f260 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
2f270 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
2f280 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
2f290 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
2f2a0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2f2b0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
2f2c0 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
2f2d0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2f2e0 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
2f2f0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2f300 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2f310 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
2f320 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2f330 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
2f340 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2f350 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2f360 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
2f370 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
2f380 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2f390 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2f3a0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
2f3b0 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
2f3c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f3d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
2f3e0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2f3f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2f400 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
2f410 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
2f420 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
2f430 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
2f440 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
2f450 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
2f460 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2f470 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
2f480 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2f490 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2f4a0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2f4b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2f4c0 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
2f4d0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
2f4e0 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
2f4f0 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
2f500 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
2f510 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
2f520 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
2f530 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
2f540 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
2f550 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
2f560 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
2f570 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
2f580 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
2f590 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
2f5a0 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
2f5b0 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
2f5c0 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
2f5d0 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
2f5e0 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
2f5f0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
2f600 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
2f610 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
2f620 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
2f630 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
2f640 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
2f650 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
2f660 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2f670 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2f680 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2f690 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2f6a0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
2f6b0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2f6c0 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
2f6d0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2f6e0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2f6f0 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
2f700 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2f710 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2f720 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2f730 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
2f740 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2f750 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2f760 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2f770 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2f780 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
2f790 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
2f7a0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
2f7b0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2f7c0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2f7d0 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
2f7e0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2f7f0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2f800 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
2f810 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
2f820 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2f830 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2f840 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
2f850 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
2f860 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2f870 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2f880 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2f890 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
2f8a0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2f8b0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2f8c0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c  td> [CAST] to BL
2f8d0 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  OB.** <tr><td>  
2f8e0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
2f8f0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
2f900 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
2f910 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2f920 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2f930 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2f940 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
2f950 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2f960 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
2f970 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
2f980 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2f990 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2f9a0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
2f9b0 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
2f9c0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
2f9d0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
2f9e0 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
2f9f0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2fa00 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2fa10 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2fa20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2fa30 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
2fa40 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2fa50 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
2fa60 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
2fa70 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
2fa80 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
2fa90 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
2faa0 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
2fab0 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
2fac0 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2fad0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2fae0 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2faf0 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2fb00 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2fb10 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2fb20 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2fb30 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2fb40 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2fb50 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2fb60 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2fb70 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2fb80 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2fb90 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2fba0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2fbb0 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2fbc0 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2fbd0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2fbe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2fbf0 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2fc00 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2fc10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2fc20 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2fc30 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2fc40 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2fc50 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2fc60 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2fc70 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2fc80 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2fc90 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2fca0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2fcb0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2fcc0 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2fcd0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2fce0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2fcf0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2fd00 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2fd10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2fd20 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2fd30 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2fd40 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2fd50 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2fd60 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2fd70 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2fd80 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2fd90 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2fda0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2fdb0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2fdc0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2fdd0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2fde0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2fdf0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2fe00 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2fe10 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2fe20 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2fe30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2fe40 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2fe50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fe60 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2fe70 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2fe80 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2fe90 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2fea0 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2feb0 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2fec0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2fed0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2fee0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2fef0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2ff00 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2ff10 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2ff20 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2ff30 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2ff40 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2ff50 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2ff60 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2ff70 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2ff80 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2ff90 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2ffa0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2ffb0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2ffc0 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2ffd0 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2ffe0 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2fff0 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
30000 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
30010 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
30020 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
30030 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
30040 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
30050 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
30060 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
30070 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
30080 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
30090 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
300a0 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
300b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
300c0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
300d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
300e0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
300f0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
30100 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
30110 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
30120 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
30130 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
30140 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
30150 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
30160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30170 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
30180 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
30190 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
301a0 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
301b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
301c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
301d0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
301e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
301f0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
30200 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
30210 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
30220 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
30230 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
30240 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
30250 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
30260 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
30270 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
30280 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
30290 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
302a0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
302b0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
302c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
302d0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
302e0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
302f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
30300 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
30310 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
30320 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
30330 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
30340 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30350 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
30360 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
30370 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
30380 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
30390 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
303a0 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
303b0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
303c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
303d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
303e0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
303f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
30400 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
30410 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
30420 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
30430 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
30440 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
30450 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
30460 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
30470 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
30480 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
30490 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
304a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
304b0 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
304c0 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
304d0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
304e0 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
304f0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
30500 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
30510 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
30520 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
30530 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
30540 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
30550 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
30560 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
30570 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
30580 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
30590 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
305a0 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
305b0 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
305c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
305d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
305e0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
305f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
30600 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ].)^.*/.SQLITE_A
30610 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
30620 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
30630 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
30640 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
30650 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
30660 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30670 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30680 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
30690 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
306a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
306b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
306c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
306d0 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
306e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
306f0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
30700 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
30710 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
30720 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
30730 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30740 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
30750 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
30760 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
30770 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
30780 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30790 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
307a0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
307b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
307c0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
307d0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
307e0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
307f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
30800 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
30810 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30820 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
30830 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
30840 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
30850 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
30860 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
30870 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
30880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
30890 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
308a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
308b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
308c0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
308d0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
308e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
308f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
30900 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
30910 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
30920 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30930 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
30940 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
30950 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
30960 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
30970 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
30980 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
30990 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
309a0 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
309b0 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
309c0 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
309d0 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
309e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
309f0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
30a00 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
30a10 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
30a20 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
30a30 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
30a40 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
30a50 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
30a60 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
30a70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30a80 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
30a90 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
30aa0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
30ab0 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
30ac0 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
30ad0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30ae0 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
30af0 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
30b00 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
30b10 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
30b20 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
30b30 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
30b40 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
30b50 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
30b60 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
30b70 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
30b80 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
30b90 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
30ba0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
30bb0 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
30bc0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30bd0 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
30be0 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
30bf0 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
30c00 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
30c10 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
30c20 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
30c30 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
30c40 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
30c50 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
30c60 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
30c70 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
30c80 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
30c90 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
30ca0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30cb0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
30cc0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
30cd0 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
30ce0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
30cf0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
30d00 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
30d10 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
30d20 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
30d30 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
30d40 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
30d50 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
30d60 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  uption..*/.SQLIT
30d70 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
30d80 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
30d90 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
30da0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30db0 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
30dc0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
30dd0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ect.**.** The sq
30de0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
30df0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
30e00 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
30e10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30e20 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
30e30 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
30e40 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
30e50 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
30e60 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
30e70 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
30e80 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
30e90 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
30ea0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
30eb0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
30ec0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
30ed0 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
30ee0 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
30ef0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
30f00 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
30f10 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
30f20 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
30f30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
30f40 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
30f50 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
30f60 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
30f70 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
30f80 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
30f90 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
30fa0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
30fb0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
30fc0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
30fd0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
30fe0 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
30ff0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
31000 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
31010 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
31020 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
31030 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
31040 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
31050 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
31060 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
31070 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
31080 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
31090 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
310a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
310b0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
310c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
310d0 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
310e0 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
310f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
31100 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
31110 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
31120 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
31130 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
31140 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
31150 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
31160 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
31170 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
31180 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
31190 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
311a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
311b0 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ] S..*/.SQLITE_A
311c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  PI int sqlite3_r
311d0 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
311e0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
311f0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
31200 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
31210 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
31220 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
31230 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
31240 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
31250 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
31260 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
31270 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
31280 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
31290 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
312a0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54  ctions}.**.** ^T
312b0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
312c0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
312d0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
312e0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
312f0 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
31300 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
31310 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
31320 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
31330 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
31340 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
31350 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
31360 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
31370 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
31380 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
31390 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
313a0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
313b0 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
313c0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
313d0 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
313e0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
313f0 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
31400 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
31410 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
31420 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
31430 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
31440 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
31450 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
31460 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
31470 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
31480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31490 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
314a0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
314b0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
314c0 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
314d0 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
314e0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
314f0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
31500 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
31510 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
31520 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
31530 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
31540 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31550 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
31560 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
31570 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
31580 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
31590 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
315a0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
315b0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
315c0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
315d0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
315e0 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
315f0 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
31600 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
31610 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
31620 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
31630 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
31640 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
31650 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
31660 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
31670 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
31680 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
31690 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
316a0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
316b0 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
316c0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
316d0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
316e0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
316f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
31700 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
31710 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
31720 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
31730 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
31740 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
31750 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
31760 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
31770 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
31780 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
31790 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
317a0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
317b0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
317c0 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
317d0 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
317e0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
317f0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
31800 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
31810 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
31820 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
31830 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
31840 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
31850 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
31860 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
31870 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
31880 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
31890 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
318a0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
318b0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
318c0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
318d0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
318e0 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
318f0 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
31900 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
31910 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
31920 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
31930 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
31940 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
31950 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
31960 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
31970 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
31980 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
31990 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
319a0 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
319b0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
319c0 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
319d0 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
319e0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
319f0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
31a00 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
31a10 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
31a20 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
31a30 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
31a40 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
31a50 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
31a60 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
31a70 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
31a80 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
31a90 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
31aa0 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
31ab0 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
31ac0 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
31ad0 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
31ae0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
31af0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
31b00 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
31b10 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
31b20 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
31b30 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
31b40 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
31b50 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
31b60 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
31b70 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
31b80 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
31b90 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
31ba0 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
31bb0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
31bc0 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
31bd0 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
31be0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
31bf0 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
31c00 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
31c10 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
31c20 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
31c30 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
31c40 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
31c50 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
31c60 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
31c70 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
31c80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
31c90 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
31ca0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
31cb0 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
31cc0 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
31cd0 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
31ce0 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
31cf0 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
31d00 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
31d10 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
31d20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
31d30 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
31d40 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
31d50 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
31d60 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
31d70 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
31d80 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
31d90 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
31da0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
31db0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31dc0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
31dd0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
31de0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
31df0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
31e00 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
31e10 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
31e20 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
31e30 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
31e40 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
31e50 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
31e60 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
31e70 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
31e80 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
31e90 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
31ea0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
31eb0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
31ec0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
31ed0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
31ee0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
31ef0 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
31f00 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
31f10 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
31f20 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
31f30 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
31f40 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
31f50 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
31f60 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
31f70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31f80 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
31f90 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
31fa0 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
31fb0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
31fc0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
31fd0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
31fe0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
31ff0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
32000 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
32010 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
32020 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
32030 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
32040 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
32050 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32060 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
32070 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
32080 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
32090 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
320a0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
320b0 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
320c0 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
320d0 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
320e0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
320f0 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
32100 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
32110 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
32120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
32130 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
32140 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
32150 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
32160 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
32170 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32180 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
32190 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
321a0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
321b0 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
321c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
321d0 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
321e0 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
321f0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
32200 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
32210 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
32220 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
32230 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
32240 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
32250 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32260 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
32270 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
32280 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
32290 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
322a0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
322b0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
322c0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
322d0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
322e0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
322f0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
32300 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
32310 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
32320 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
32330 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
32340 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
32350 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
32360 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
32370 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
32380 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
32390 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
323a0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
323b0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
323c0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
323d0 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
323e0 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
323f0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
32400 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32410 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
32420 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
32430 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
32440 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
32450 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
32460 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
32470 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
32480 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
32490 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
324a0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
324b0 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
324c0 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
324d0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
324e0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
324f0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
32500 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
32510 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
32520 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
32530 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
32540 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
32550 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
32560 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
32570 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
32580 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
32590 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
325a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
325b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
325c0 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
325d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
325e0 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
325f0 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
32600 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
32610 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
32620 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
32630 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
32640 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
32650 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
32660 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
32670 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
32680 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
32690 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
326a0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
326b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
326c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
326d0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
326e0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
326f0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
32700 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
32710 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
32720 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
32730 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
32740 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
32750 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
32760 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
32770 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32780 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
32790 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
327a0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
327b0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51  _context*).);.SQ
327c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
327d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
327e0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
327f0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
32800 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
32810 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
32820 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
32830 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
32840 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
32850 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
32860 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
32870 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
32880 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
32890 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
328a0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
328b0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
328c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
328d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
328e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
328f0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
32900 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
32910 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
32920 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
32930 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
32940 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
32950 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
32960 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
32970 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
32980 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
32990 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
329a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
329b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
329c0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
329d0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
329e0 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
329f0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
32a00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32a10 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
32a20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
32a30 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
32a40 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
32a50 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
32a60 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
32a70 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
32a80 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
32a90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
32aa0 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
32ab0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
32ac0 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
32ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
32ae0 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
32af0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
32b00 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
32b10 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
32b20 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
32b30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
32b40 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
32b50 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20    /* Deprecated 
32b60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32b70 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
32b80 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
32b90 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32ba0 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
32bb0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
32bc0 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ion Flags.**.** 
32bd0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
32be0 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65  may be ORed toge
32bf0 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a  ther with the .*
32c00 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
32c10 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
32c20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65  encoding] as the
32c30 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
32c40 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
32c50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
32c60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
32c70 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
32c80 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
32c90 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
32ca0 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  n_v2()]..*/.#def
32cb0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52  ine SQLITE_DETER
32cc0 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30  MINISTIC    0x80
32cd0 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
32ce0 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
32cf0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
32d00 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
32d10 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
32d20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
32d30 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
32d40 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
32d50 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
32d60 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
32d70 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
32d80 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
32d90 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
32da0 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
32db0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
32dc0 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
32dd0 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
32de0 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
32df0 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
32e00 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
32e10 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
32e20 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
32e30 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
32e40 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
32e50 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
32e60 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
32e70 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
32e80 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
32e90 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
32ea0 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
32eb0 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
32ec0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
32ed0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
32ee0 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
32ef0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
32f00 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
32f10 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
32f20 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
32f30 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
32f40 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
32f50 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  mt*);.SQLITE_API
32f60 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
32f70 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
32f80 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
32f90 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
32fa0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
32fb0 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
32fc0 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
32fd0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
32fe0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
32ff0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
33000 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
33010 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
33020 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20  _int64,int),.   
33030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33040 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33     void*,sqlite3
33050 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
33060 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33070 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
33080 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
33090 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
330a0 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
330b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
330c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
330d0 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
330e0 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
330f0 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
33100 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
33110 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
33120 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
33130 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
33140 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
33150 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
33160 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
33170 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
33180 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
33190 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
331a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
331b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
331c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
331d0 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
331e0 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
331f0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
33200 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
33210 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
33220 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
33230 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
33240 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
33250 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
33260 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
33270 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
33280 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
33290 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
332a0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
332b0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
332c0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
332d0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
332e0 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
332f0 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
33300 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
33310 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
33320 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
33330 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
33340 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
33350 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
33360 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
33370 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
33380 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
33390 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
333a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
333b0 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
333c0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
333d0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
333e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
333f0 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
33400 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
33410 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
33420 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
33430 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20  ept that  these 
33440 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
33450 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
33460 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
33470 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
33480 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
33490 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
334a0 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
334b0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
334c0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
334d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
334e0 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
334f0 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
33500 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
33510 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
33520 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
33530 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
33540 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
33550 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
33560 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
33570 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
33580 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
33590 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
335a0 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
335b0 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
335c0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
335d0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
335e0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
335f0 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
33600 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
33610 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
33620 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
33630 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
33640 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
33650 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
33660 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
33670 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
33680 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
33690 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
336a0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
336b0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
336c0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
336d0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
336e0 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
336f0 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
33700 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
33710 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
33720 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
33730 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
33740 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
33750 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
33760 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
33770 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
33780 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
33790 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
337a0 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
337b0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
337c0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
337d0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
337e0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
337f0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
33800 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
33810 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33820 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
33830 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33840 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
33850 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
33860 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
33870 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
33880 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
33890 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
338a0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
338b0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
338c0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
338d0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
338e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
338f0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
33900 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
33910 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
33920 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
33930 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
33940 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
33950 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
33960 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
33970 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33980 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
33990 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
339a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
339b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
339c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
339d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
339e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
339f0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
33a00 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
33a10 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  I double sqlite3
33a20 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
33a30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
33a40 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
33a50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
33a60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33a70 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
33a80 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
33a90 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
33aa0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
33ab0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
33ac0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
33ad0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33ae0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
33af0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
33b00 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
33b10 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
33b20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33b30 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
33b40 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
33b50 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
33b60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
33b70 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
33b80 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
33b90 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
33ba0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
33bb0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
33bc0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
33bd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33be0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
33bf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
33c00 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
33c10 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
33c20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
33c30 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
33c40 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
33c50 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
33c60 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
33c70 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
33c80 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
33c90 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
33ca0 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
33cb0 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
33cc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
33cd0 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
33ce0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
33cf0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
33d00 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
33d10 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
33d20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
33d30 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
33d40 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
33d50 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
33d60 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
33d70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
33d80 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
33d90 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
33da0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
33db0 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
33dc0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
33dd0 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
33de0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
33df0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
33e00 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
33e10 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
33e20 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
33e30 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33e40 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
33e50 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
33e60 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
33e70 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
33e80 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
33e90 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
33ea0 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
33eb0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
33ec0 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
33ed0 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
33ee0 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
33ef0 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
33f00 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
33f10 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
33f20 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
33f30 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
33f40 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
33f50 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
33f60 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
33f70 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
33f80 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33f90 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
33fa0 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
33fb0 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
33fc0 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
33fd0 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
33fe0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
33ff0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
34000 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
34010 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a  a NULL pointer .
34020 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61  ** when first ca
34030 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73  lled if N is les
34040 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
34050 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
34060 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
34070 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
34080 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
34090 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
340a0 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
340b0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
340c0 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
340d0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
340e0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
340f0 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
34100 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
34110 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
34120 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
34130 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
34140 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
34150 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
34160 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
34170 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
34180 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
34190 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
341a0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20  * allocation.)^ 
341b0 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e   Within the xFin
341c0 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20  al callback, it 
341d0 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20  is customary to 
341e0 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61  set.** N=0 in ca
341f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
34200 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
34210 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f  (C,N) so that no
34220 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d   .** pointless m
34230 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
34240 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e  s occur..**.** ^
34250 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
34260 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
34270 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
34280 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
34290 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
342a0 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
342b0 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
342c0 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
342d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
342e0 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
342f0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
34300 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
34310 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
34320 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
34330 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
34340 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
34350 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
34360 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
34370 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
34380 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
34390 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
343a0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
343b0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
343c0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
343d0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
343e0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
343f0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
34400 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
34410 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
34420 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
34430 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
34440 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
34450 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
34460 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
34470 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
34480 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
34490 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
344a0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
344b0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
344c0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
344d0 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
344e0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
344f0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
34500 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
34510 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
34520 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34530 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
34540 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
34550 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
34560 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
34570 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
34580 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
34590 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
345a0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
345b0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
345c0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
345d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
345e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
345f0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
34600 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
34610 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
34620 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
34630 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34640 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
34650 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
34660 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
34670 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
34680 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
34690 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
346a0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
346b0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
346c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
346d0 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
346e0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
346f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34700 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
34710 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
34720 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
34730 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
34740 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
34750 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
34760 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
34770 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51   function..*/.SQ
34780 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
34790 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
347a0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
347b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
347c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
347d0 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
347e0 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
347f0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  ese functions ma
34800 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f  y be used by (no
34810 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c  n-aggregate) SQL
34820 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
34830 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
34840 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
34850 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
34860 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
34870 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
34880 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
34890 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
348a0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
348b0 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
348c0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
348d0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
348e0 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
348f0 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
34900 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d  served.  An exam
34910 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20  ple.** of where 
34920 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73  this might be us
34930 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67  eful is in a reg
34940 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
34950 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63  matching.** func
34960 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
34970 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
34980 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
34990 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72  sion can be stor
349a0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
349b0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
349c0 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  h the pattern st
349d0 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20  ring.  .** Then 
349e0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70  as long as the p
349f0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65  attern string re
34a00 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a  mains the same,.
34a10 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  ** the compiled 
34a20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
34a30 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
34a40 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
34a50 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
34a60 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
34a70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34a80 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
34a90 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
34aa0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
34ab0 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
34ac0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
34ad0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
34ae0 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
34af0 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
34b00 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
34b10 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
34b20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34b30 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65  ction. ^If there
34b40 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a   is no metadata.
34b50 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
34b60 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  th the function 
34b70 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73  argument, this s
34b80 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
34b90 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ta() interface.*
34ba0 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  * returns a NULL
34bb0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
34bc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
34bd0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
34be0 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
34bf0 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20  s P as metadata 
34c00 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
34c10 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
34c20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34c30 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  ned function.  ^
34c40 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
34c50 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
34c60 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20  et_auxdata(C,N) 
34c70 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68  return P from th
34c80 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
34c90 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34ca0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61  data(C,N,P,X) ca
34cb0 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61  ll if the metada
34cc0 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69  ta is still vali
34cd0 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20  d or.** NULL if 
34ce0 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73  the metadata has
34cf0 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e   been discarded.
34d00 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20  .** ^After each 
34d10 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
34d20 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
34d30 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20  P,X) where X is 
34d40 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c  not NULL,.** SQL
34d50 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
34d60 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  the destructor f
34d70 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70  unction X with p
34d80 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74  arameter P exact
34d90 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e  ly.** once, when
34da0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
34db0 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53   discarded..** S
34dc0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
34dd0 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74   discard the met
34de0 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d  adata at any tim
34df0 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75  e, including: <u
34e00 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  l>.** <li> when 
34e10 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
34e20 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
34e30 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72  eter changes, or
34e40 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73  .** <li> when [s
34e50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
34e60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
34e70 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
34e80 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  d for the.**    
34e90 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c    SQL statement,
34ea0 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e   or.** <li> when
34eb0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34ec0 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65  data() is invoke
34ed0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73  d again on the s
34ee0 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f  ame parameter, o
34ef0 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67  r.** <li> during
34f00 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71   the original sq
34f10 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
34f20 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20  a() call when a 
34f30 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20  memory .**      
34f40 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
34f50 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e   occurs. </ul>)^
34f60 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20  .**.** Note the 
34f70 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70  last bullet in p
34f80 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20  articular.  The 
34f90 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20  destructor X in 
34fa0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
34fb0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
34fc0 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
34fd0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
34fe0 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69  fore the.** sqli
34ff0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
35000 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e  ) interface even
35010 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65   returns.  Hence
35020 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
35030 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64  data().** should
35040 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20   be called near 
35050 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
35060 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
35070 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a  tation and the.*
35080 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  * function imple
35090 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
350a0 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73   not make any us
350b0 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20  e of P after.** 
350c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
350d0 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63  ata() has been c
350e0 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  alled..**.** ^(I
350f0 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
35100 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
35110 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
35120 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
35130 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
35140 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d  ers that are com
35150 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61  pile-time consta
35160 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c  nts, including l
35170 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
35180 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
35190 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e  ] and expression
351a0 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20  s composed from 
351b0 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a  the same.)^.**.*
351c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
351d0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
351e0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
351f0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
35200 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
35210 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
35220 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
35230 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
35240 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
35250 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
35260 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
35270 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
35280 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
35290 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
352a0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
352b0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
352c0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
352d0 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
352e0 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
352f0 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
35300 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
35310 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
35320 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
35330 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
35340 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
35350 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
35360 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
35370 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
35380 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
35390 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
353a0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
353b0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
353c0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
353d0 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
353e0 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
353f0 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
35400 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
35410 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
35420 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
35430 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
35440 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
35450 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
35460 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
35470 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
35480 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
35490 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
354a0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
354b0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
354c0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
354d0 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
354e0 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
354f0 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
35500 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
35510 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
35520 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  rs..*/.typedef v
35530 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
35540 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
35550 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
35560 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
35570 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
35580 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
35590 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
355a0 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
355b0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
355c0 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
355d0 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
355e0 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
355f0 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
35600 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
35610 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
35620 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
35630 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
35640 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
35650 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
35660 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
35670 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
35680 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
35690 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
356a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
356b0 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
356c0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
356d0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
356e0 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
356f0 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
35700 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
35710 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
35720 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
35730 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
35740 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
35750 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
35760 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
35770 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
35780 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
35790 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
357a0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
357b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
357c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
357d0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
357e0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
357f0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
35800 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35810 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
35820 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
35830 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
35840 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
35850 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
35860 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
35870 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
35880 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
35890 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
358a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
358b0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
358c0 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
358d0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
358e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
358f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35900 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
35910 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
35920 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
35930 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
35940 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
35950 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
35960 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
35970 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35980 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
35990 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
359a0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
359b0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
359c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
359d0 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
359e0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
359f0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
35a00 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
35a10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35a20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
35a30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
35a40 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
35a50 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
35a60 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
35a70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
35a80 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
35a90 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ion..** ^SQLite 
35aa0 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
35ab0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
35ac0 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
35ad0 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
35ae0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
35af0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35b00 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
35b10 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
35b20 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53  ror message.  ^S
35b30 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
35b40 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
35b50 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
35b60 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
35b70 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
35b80 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  8. ^SQLite.** in
35b90 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
35ba0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
35bb0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35bc0 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
35bd0 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
35be0 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68  der.  ^If the th
35bf0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
35c00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35c10 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
35c20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35c30 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
35c40 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
35c50 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
35c60 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
35c70 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
35c80 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
35c90 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
35ca0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
35cb0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
35cc0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
35cd0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
35ce0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
35cf0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
35d00 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
35d10 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
35d20 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
35d30 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
35d40 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
35d50 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
35d60 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
35d70 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
35d80 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
35d90 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
35da0 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
35db0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
35dc0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
35dd0 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
35de0 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
35df0 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
35e00 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
35e10 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
35e20 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
35e30 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
35e40 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
35e50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35e60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
35e70 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
35e80 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
35e90 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
35ea0 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
35eb0 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
35ec0 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
35ed0 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a  .  ^By default,.
35ee0 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
35ef0 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
35f00 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e  R.  ^A subsequen
35f10 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
35f20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
35f30 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
35f40 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
35f50 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
35f60 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
35f70 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ERROR..**.** ^Th
35f80 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35f90 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20  _error_toobig() 
35fa0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
35fb0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
35fc0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
35fd0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
35fe0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
35ff0 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
36000 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
36010 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36020 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20  t_error_nomem() 
36030 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
36040 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
36050 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
36060 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
36070 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
36080 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
36090 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
360a0 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
360b0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
360c0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
360d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
360e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
360f0 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
36100 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
36110 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
36120 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
36130 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
36140 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
36150 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
36160 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
36170 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
36180 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36190 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
361a0 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
361b0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
361c0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
361d0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
361e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
361f0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
36200 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
36210 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
36220 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
36230 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36240 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
36250 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36260 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36270 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
36280 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
36290 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
362a0 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
362b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
362c0 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
362d0 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
362e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
362f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36300 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36310 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
36320 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
36330 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
36340 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
36350 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
36360 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
36370 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
36380 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
36390 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
363a0 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
363b0 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
363c0 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
363d0 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
363e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
363f0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
36400 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
36410 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
36420 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
36430 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
36440 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
36450 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
36460 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
36470 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
36480 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
36490 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
364a0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
364b0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
364c0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
364d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
364e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
364f0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
36500 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
36510 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
36520 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
36530 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
36540 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
36550 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
36560 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
36570 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
36580 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
36590 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
365a0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
365b0 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
365c0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
365d0 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
365e0 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
365f0 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
36600 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
36610 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
36620 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
36630 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
36640 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
36650 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
36660 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
36670 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
36680 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
36690 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
366a0 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
366b0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
366c0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
366d0 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
366e0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
366f0 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
36700 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
36710 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
36720 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
36730 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
36740 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
36750 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
36760 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
36770 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
36780 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
36790 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
367a0 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
367b0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
367c0 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
367d0 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
367e0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
367f0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
36800 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
36810 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
36820 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
36830 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
36840 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
36850 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36860 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
36870 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
36880 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
36890 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
368a0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
368b0 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
368c0 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
368d0 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
368e0 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
368f0 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
36900 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
36910 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
36920 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
36930 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
36940 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
36950 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
36960 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
36970 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
36980 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
36990 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
369a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
369b0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
369c0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
369d0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
369e0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
369f0 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
36a00 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
36a10 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
36a20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
36a30 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
36a40 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
36a50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
36a60 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
36a70 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
36a80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
36a90 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
36aa0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
36ab0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
36ac0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36ad0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
36ae0 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
36af0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
36b00 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
36b10 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
36b20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
36b30 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
36b40 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
36b50 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
36b60 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
36b70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
36b80 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
36b90 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
36ba0 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
36bb0 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
36bc0 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
36bd0 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
36be0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
36bf0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
36c00 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
36c10 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36c20 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36c30 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
36c40 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
36c50 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
36c60 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
36c70 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
36c80 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
36c90 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
36ca0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
36cb0 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
36cc0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
36cd0 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
36ce0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
36cf0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
36d00 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
36d10 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
36d20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
36d30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36d40 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
36d50 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
36d60 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
36d70 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
36d80 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
36d90 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  efined..*/.SQLIT
36da0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
36db0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
36dc0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36dd0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
36de0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
36df0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
36e00 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36e10 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
36e20 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
36e30 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  le);.SQLITE_API 
36e40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36e50 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
36e60 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
36e70 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53  t char*, int);.S
36e80 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
36e90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36ea0 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
36eb0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
36ec0 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  id*, int);.SQLIT
36ed0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
36ee0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
36ef0 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
36f00 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
36f10 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
36f20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
36f30 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
36f40 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  text*);.SQLITE_A
36f50 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
36f60 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
36f70 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
36f80 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
36f90 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
36fa0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
36fb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
36fc0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
36fd0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36fe0 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
36ff0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
37000 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49  te3_int64);.SQLI
37010 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
37020 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
37030 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37040 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
37050 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37060 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
37070 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
37080 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
37090 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
370a0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
370b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
370c0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
370d0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
370e0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
370f0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
37100 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37110 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
37120 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37130 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
37140 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
37150 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
37160 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37170 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
37180 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
37190 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
371a0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
371b0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
371c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
371d0 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
371e0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
371f0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
37200 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37210 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
37220 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37230 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
37240 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
37250 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
37260 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e  equences.**.** ^
37270 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
37280 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20  add, remove, or 
37290 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74  modify a [collat
372a0 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a  ion] associated.
372b0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
372c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
372d0 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
372e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
372f0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
37300 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  me of the collat
37310 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73  ion is a UTF-8 s
37320 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
37330 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37340 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
37350 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37360 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
37370 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
37380 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
37390 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
373a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
373b0 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  on16()..** ^Coll
373c0 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74  ation names that
373d0 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61   compare equal a
373e0 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c  ccording to [sql
373f0 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d  ite3_strnicmp()]
37400 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
37410 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d  ed to be the sam
37420 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e name..**.** ^(
37430 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
37440 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75  nt (eTextRep) mu
37450 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  st be one of the
37460 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c   constants:.** <
37470 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
37480 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c  ITE_UTF8],.** <l
37490 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
374a0 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  LE],.** <li> [SQ
374b0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
374c0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
374d0 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  TF16], or.** <li
374e0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  > [SQLITE_UTF16_
374f0 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75  ALIGNED]..** </u
37500 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65  l>)^.** ^The eTe
37510 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64  xtRep argument d
37520 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e  etermines the en
37530 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67  coding of string
37540 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74  s passed.** to t
37550 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
37560 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20  ction callback, 
37570 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54  xCallback..** ^T
37580 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
37590 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54  ] and [SQLITE_UT
375a0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
375b0 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70  ues for eTextRep
375c0 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67  .** force string
375d0 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69  s to be UTF16 wi
375e0 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  th native byte o
375f0 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  rder..** ^The [S
37600 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
37610 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65  NED] value for e
37620 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73  TextRep forces s
37630 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a  trings to begin.
37640 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79  ** on an even by
37650 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a  te address..**.*
37660 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72  * ^The fourth ar
37670 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73  gument, pArg, is
37680 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
37690 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
376a0 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  t is passed.** t
376b0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
376c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
376d0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
376e0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  nction callback.
376f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
37700 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c  h argument, xCal
37710 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e  lback, is a poin
37720 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ter to the colla
37730 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ting function..*
37740 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c  * ^Multiple coll
37750 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
37760 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
37770 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  d using the same
37780 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74   name but.** wit
37790 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  h different eTex
377a0 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20  tRep parameters 
377b0 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  and SQLite will 
377c0 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a  use whichever.**
377d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
377e0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
377f0 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e  unt of data tran
37800 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  sformation..** ^
37810 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b  If the xCallback
37820 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c   argument is NUL
37830 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  L then the colla
37840 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
37850 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57  .** deleted.  ^W
37860 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e  hen all collatin
37870 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69  g functions havi
37880 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
37890 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a   are deleted,.**
378a0 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20   that collation 
378b0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61  is no longer usa
378c0 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
378d0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
378e0 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  on callback is i
378f0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f  nvoked with a co
37900 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a  py of the pArg .
37910 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  ** application d
37920 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ata pointer and 
37930 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73  with two strings
37940 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
37950 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
37960 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72   the eTextRep ar
37970 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c  gument.  The col
37980 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37990 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a  must return an.*
379a0 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69  * integer that i
379b0 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  s negative, zero
379c0 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a  , or positive.**
379d0 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74   if the first st
379e0 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
379f0 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  n, equal to, or 
37a00 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
37a10 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70   second,.** resp
37a20 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c  ectively.  A col
37a30 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37a40 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75  must always retu
37a50 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77  rn the same answ
37a60 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20  er.** given the 
37a70 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66  same inputs.  If
37a80 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c   two or more col
37a90 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
37aa0 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a   are registered.
37ab0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63  ** to the same c
37ac0 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75  ollation name (u
37ad0 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65  sing different e
37ae0 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20  TextRep values) 
37af0 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74  then all.** must
37b00 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c   give an equival
37b10 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20  ent answer when 
37b20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75  invoked with equ
37b30 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e  ivalent strings.
37b40 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  .** The collatin
37b50 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
37b60 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69  obey the followi
37b70 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f  ng properties fo
37b80 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73  r all.** strings
37b90 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a   A, B, and C:.**
37ba0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
37bb0 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d   If A==B then B=
37bc0 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =A..** <li> If A
37bd0 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65  ==B and B==C the
37be0 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20  n A==C..** <li> 
37bf0 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42  If A&lt;B THEN B
37c00 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49  &gt;A..** <li> I
37c10 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c  f A&lt;B and B&l
37c20 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e  t;C then A&lt;C.
37c30 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
37c40 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66  If a collating f
37c50 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e  unction fails an
37c60 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63  y of the above c
37c70 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
37c80 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67  hat.** collating
37c90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65   function is  re
37ca0 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65  gistered and use
37cb0 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
37cc0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
37cd0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
37ce0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37cf0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37d00 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
37d10 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
37d20 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
37d30 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74  * with the addit
37d40 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65  ion that the xDe
37d50 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
37d60 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72  s invoked on pAr
37d70 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  g when.** the co
37d80 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37d90 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   is deleted..** 
37da0 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74  ^Collating funct
37db0 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64  ions are deleted
37dc0 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
37dd0 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
37de0 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74  er.** calls to t
37df0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
37e00 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
37e10 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  or when the.** [
37e20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37e30 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75  ion] is closed u
37e40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
37e50 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ose()]..**.** ^T
37e60 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
37e70 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f  back is <u>not</
37e80 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65  u> called if the
37e90 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65   .** sqlite3_cre
37ea0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
37eb0 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  () function fail
37ec0 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  s.  Applications
37ed0 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20   that invoke.** 
37ee0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37ef0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69  ollation_v2() wi
37f00 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44  th a non-NULL xD
37f10 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20  estroy argument 
37f20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b  should .** check
37f30 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
37f40 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20   and dispose of 
37f50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
37f60 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  data pointer.** 
37f70 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65  themselves rathe
37f80 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67  r than expecting
37f90 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20   SQLite to deal 
37fa0 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d  with it for them
37fb0 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66  ..** This is dif
37fc0 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72  ferent from ever
37fd0 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
37fe0 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69  nterface.  The i
37ff0 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a  nconsistency .**
38000 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20   is unfortunate 
38010 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  but cannot be ch
38020 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72  anged without br
38030 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73  eaking backwards
38040 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69   .** compatibili
38050 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ty..**.** See al
38060 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
38070 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
38080 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
38090 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
380a0 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  6()]..*/.SQLITE_
380b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
380c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
380d0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
380e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
380f0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
38100 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
38110 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
38120 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
38130 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
38140 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53  onst void*).);.S
38150 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
38160 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
38170 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
38180 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
38190 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
381a0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
381b0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
381c0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
381d0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
381e0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
381f0 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
38200 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
38210 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
38220 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
38230 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
38240 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
38250 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
38260 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
38270 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
38280 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
38290 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
382a0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
382b0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
382c0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
382d0 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
382e0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
382f0 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
38300 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
38310 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
38320 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
38330 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
38340 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
38350 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
38360 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
38370 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
38380 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38390 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
383a0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
383b0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
383c0 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
383d0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
383e0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
383f0 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
38400 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
38410 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
38420 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
38430 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
38440 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
38450 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
38460 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
38470 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
38480 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
38490 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
384a0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
384b0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
384c0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
384d0 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
384e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
384f0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
38500 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
38510 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
38520 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
38530 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
38540 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
38550 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
38560 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
38570 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
38580 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
38590 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
385a0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
385b0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
385c0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
385d0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
385e0 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
385f0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
38600 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
38610 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
38620 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
38630 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
38640 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
38650 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
38660 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
38670 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
38680 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
38690 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
386a0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
386b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
386c0 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
386d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
386e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
386f0 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
38700 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
38710 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
38720 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
38730 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
38740 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
38750 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
38760 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
38770 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
38780 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _