System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 69a0024d269e1462b08a923ec39218f8e86d07d1:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 37 2e 31 33 2e 20 20  ersion 3.7.13.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e  atic.#endif.#ifn
0550: 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23  def SQLITE_API.#
0560: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41   define SQLITE_A
0570: 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a  PI.#endif./*****
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20  ********* Begin 
0590: 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68  file sqliteInt.h
05a0: 20 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 2a 2f 0a 2f 2a 0a 2a 2a 20  ********/./*.** 
05d0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31  2001 September 1
05e0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  5.**.** The auth
05f0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70  or disclaims cop
0600: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73  yright to this s
0610: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20  ource code.  In 
0620: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65  place of.** a le
0630: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65  gal notice, here
0640: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a   is a blessing:.
0650: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  **.**    May you
0660: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74   do good and not
0670: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79   evil..**    May
0680: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76   you find forgiv
0690: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65  eness for yourse
06a0: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f  lf and forgive o
06b0: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79  thers..**    May
06c0: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c   you share freel
06d0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20  y, never taking 
06e0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69  more than you gi
06f0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ve..**.*********
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 2a  ****************
0740: 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74  .** Internal int
0750: 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f  erface definitio
0760: 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a  ns for SQLite..*
0770: 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51  *.*/.#ifndef _SQ
0780: 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69  LITEINT_H_.#defi
0790: 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f  ne _SQLITEINT_H_
07a0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64  ../*.** These #d
07b0: 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e  efines should en
07c0: 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73  able >2GB file s
07d0: 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20  upport on POSIX 
07e0: 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  if the.** underl
07f0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
0800: 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69  ystem supports i
0810: 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61  t.  If the OS la
0820: 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c  cks.** large fil
0830: 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66  e support, or if
0840: 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f   the OS is windo
0850: 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64  ws, these should
0860: 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   be no-ops..**.*
0870: 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20  * Ticket #2739: 
0880: 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f   The _LARGEFILE_
0890: 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73  SOURCE macro mus
08a0: 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20  t appear before 
08b0: 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69  any.** system #i
08c0: 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c  ncludes.  Hence,
08d0: 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63   this block of c
08e0: 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20  ode must be the 
08f0: 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f  very first.** co
0900: 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65  de in all source
0910: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61   files..**.** La
0920: 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74  rge file support
0930: 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64   can be disabled
0940: 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c   using the -DSQL
0950: 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20  ITE_DISABLE_LFS 
0960: 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65  switch.** on the
0970: 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e   compiler comman
0980: 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73  d line.  This is
0990: 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f   necessary if yo
09a0: 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a  u are compiling.
09b0: 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d  ** on a recent m
09c0: 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20  achine (ex: Red 
09d0: 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75  Hat 7.2) but you
09e0: 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20   want your code 
09f0: 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e  to work.** on an
0a00: 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28   older machine (
0a10: 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29  ex: Red Hat 6.0)
0a20: 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c  .  If you compil
0a30: 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32  e on Red Hat 7.2
0a40: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73  .** without this
0a50: 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20   option, LFS is 
0a60: 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53  enable.  But LFS
0a70: 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20   does not exist 
0a80: 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a  in the kernel.**
0a90: 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c   in Red Hat 6.0,
0aa0: 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e   so the code won
0ab0: 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c  't work.  Hence,
0ac0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e   for maximum bin
0ad0: 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69  ary.** portabili
0ae0: 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d  ty you should om
0af0: 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 69  it LFS..**.** Si
0b00: 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f  milar is true fo
0b10: 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53  r Mac OS X.  LFS
0b20: 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74   is only support
0b30: 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39  ed on Mac OS X 9
0b40: 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23   and later..*/.#
0b50: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49  ifndef SQLITE_DI
0b60: 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69  SABLE_LFS.# defi
0b70: 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20  ne _LARGE_FILE  
0b80: 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20       1.# ifndef 
0b90: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54  _FILE_OFFSET_BIT
0ba0: 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49  S.#   define _FI
0bb0: 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36  LE_OFFSET_BITS 6
0bc0: 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69  4.# endif.# defi
0bd0: 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f  ne _LARGEFILE_SO
0be0: 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f  URCE 1.#endif../
0bf0: 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65  *.** Include the
0c00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 68   configuration h
0c10: 65 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 20  eader output by 
0c20: 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 77  'configure' if w
0c30: 65 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  e're using the.*
0c40: 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 64  * autoconf-based
0c50: 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 66   build.*/.#ifdef
0c60: 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 4f   _HAVE_SQLITE_CO
0c70: 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 20  NFIG_H.#include 
0c80: 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 69  "config.h".#endi
0c90: 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  f../************
0ca0: 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74  ** Include sqlit
0cb0: 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 20  eLimit.h in the 
0cc0: 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65  middle of sqlite
0cd0: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  Int.h **********
0ce0: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
0cf0: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71  ** Begin file sq
0d00: 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a  liteLimit.h ****
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d30: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d 61  */./*.** 2007 Ma
0d40: 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  y 7.**.** The au
0d50: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
0d60: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
0d70: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
0d80: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0d90: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0da0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0db0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0dc0: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0dd0: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0de0: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0df0: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0e00: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0e10: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0e20: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
0e30: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
0e40: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
0e50: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ea0: 2a 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 66  **.** .** This f
0eb0: 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 69  ile defines vari
0ec0: 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 68  ous limits of wh
0ed0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 72  at SQLite can pr
0ee0: 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ocess..*/../*.**
0ef0: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   The maximum len
0f00: 67 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f 72  gth of a TEXT or
0f10: 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 20   BLOB in bytes. 
0f20: 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 6c    This also.** l
0f30: 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f  imits the size o
0f40: 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 62  f a row in a tab
0f50: 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a 0a  le or index..**.
0f60: 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d 69  ** The hard limi
0f70: 74 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 79  t is the ability
0f80: 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
0f90: 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 74  ned integer.** t
0fa0: 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a 65  o count the size
0fb0: 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 37  : 2^31-1 or 2147
0fc0: 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 64  483647..*/.#ifnd
0fd0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  ef SQLITE_MAX_LE
0fe0: 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51  NGTH.# define SQ
0ff0: 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 20  LITE_MAX_LENGTH 
1000: 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 69  1000000000.#endi
1010: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 73  f../*.** This is
1020: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1030: 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 20  ber of.**.**    
1040: 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  * Columns in a t
1050: 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c  able.**    * Col
1060: 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
1070: 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e 73  .**    * Columns
1080: 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 20   in a view.**   
1090: 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20   * Terms in the 
10a0: 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 6e  SET clause of an
10b0: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
10c0: 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20  t.**    * Terms 
10d0: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
10e0: 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
10f0: 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a 20  atement.**    * 
1100: 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 4f  Terms in the GRO
1110: 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 42  UP BY or ORDER B
1120: 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 53  Y clauses of a S
1130: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1140: 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69  .**    * Terms i
1150: 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61  n the VALUES cla
1160: 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54  use of an INSERT
1170: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
1180: 20 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20   The hard upper 
1190: 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 32  limit here is 32
11a0: 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 62  676.  Most datab
11b0: 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c 0a  ase people will.
11c0: 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 74  ** tell you that
11d0: 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d 61   in a well-norma
11e0: 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c 20  lized database, 
11f0: 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f 75  you usually shou
1200: 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 6d  ld.** not have m
1210: 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 6e  ore than a dozen
1220: 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 69   or so columns i
1230: 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 6e  n any table.  An
1240: 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 20  d if.** that is 
1250: 74 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 20  the case, there 
1260: 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 68  is no point in h
1270: 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aving more than 
1280: 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 76  a few.** dozen v
1290: 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 20  alues in any of 
12a0: 74 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 74  the other situat
12b0: 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61  ions described a
12c0: 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  bove..*/.#ifndef
12d0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55   SQLITE_MAX_COLU
12e0: 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  MN.# define SQLI
12f0: 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 30  TE_MAX_COLUMN 20
1300: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1310: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   The maximum len
1320: 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  gth of a single 
1330: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1340: 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 74   bytes..**.** It
1350: 20 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20   used to be the 
1360: 63 61 73 65 20 74 68 61 74 20 73 65 74 74 69 6e  case that settin
1370: 67 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f 20  g this value to 
1380: 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 75  zero would.** tu
1390: 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 66  rn the limit off
13a0: 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c 6f  .  That is no lo
13b0: 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 69  nger true.  It i
13c0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a 2a  s not possible.*
13d0: 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 6c  * to turn this l
13e0: 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 66  imit off..*/.#if
13f0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1400: 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 66  SQL_LENGTH.# def
1410: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53  ine SQLITE_MAX_S
1420: 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 30  QL_LENGTH 100000
1430: 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  0000.#endif../*.
1440: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  ** The maximum d
1450: 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 65  epth of an expre
1460: 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 73  ssion tree. This
1470: 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 0a   is limited to .
1480: 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62  ** some extent b
1490: 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c  y SQLITE_MAX_SQL
14a0: 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f 6d  _LENGTH. But som
14b0: 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 20  etime you might 
14c0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 63  .** want to plac
14d0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c 69  e more severe li
14e0: 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  mits on the comp
14f0: 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a 2a  lexity of an .**
1500: 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a 0a   expression..**.
1510: 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20  ** A value of 0 
1520: 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 61  used to mean tha
1530: 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
1540: 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a 2a  not enforced..**
1550: 20 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f 20   But that is no 
1560: 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 68  longer true.  Th
1570: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 73  e limit is now s
1580: 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 64  trictly enforced
1590: 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 73  .** at all times
15a0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
15b0: 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50  ITE_MAX_EXPR_DEP
15c0: 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  TH.# define SQLI
15d0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54  TE_MAX_EXPR_DEPT
15e0: 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f  H 1000.#endif../
15f0: 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d  *.** The maximum
1600: 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
1610: 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
1620: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1630: 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 6e  .** The code gen
1640: 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 6f  erator for compo
1650: 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1660: 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a 2a  ments does one.*
1670: 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 72  * level of recur
1680: 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 65  sion for each te
1690: 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 65  rm.  A stack ove
16a0: 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c 74  rflow can result
16b0: 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 65  .** if the numbe
16c0: 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 6f  r of terms is to
16d0: 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 61  o large.  In pra
16e0: 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c 0a  ctice, most SQL.
16f0: 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f 72  ** never has mor
1700: 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 65  e than 3 or 4 te
1710: 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c 75  rms.  Use a valu
1720: 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 6c  e of 0 to disabl
1730: 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 6f  e.** any limit o
1740: 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
1750: 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1760: 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a 23  unt SELECT..*/.#
1770: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41  ifndef SQLITE_MA
1780: 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  X_COMPOUND_SELEC
1790: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  T.# define SQLIT
17a0: 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53  E_MAX_COMPOUND_S
17b0: 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 66  ELECT 500.#endif
17c0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69  ../*.** The maxi
17d0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70  mum number of op
17e0: 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 20  codes in a VDBE 
17f0: 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 20  program..** Not 
1800: 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 63  currently enforc
1810: 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  ed..*/.#ifndef S
1820: 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f  QLITE_MAX_VDBE_O
1830: 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  P.# define SQLIT
1840: 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 35  E_MAX_VDBE_OP 25
1850: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  000.#endif../*.*
1860: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  * The maximum nu
1870: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
1880: 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e 63  s to an SQL func
1890: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  tion..*/.#ifndef
18a0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43   SQLITE_MAX_FUNC
18b0: 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 6e  TION_ARG.# defin
18c0: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e  e SQLITE_MAX_FUN
18d0: 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 65  CTION_ARG 127.#e
18e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  ndif../*.** The 
18f0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1900: 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 65  f in-memory page
1910: 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65  s to use for the
1920: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a 2a   main database.*
1930: 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 20  * table and for 
1940: 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 73  temporary tables
1950: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45  .  The SQLITE_DE
1960: 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45  FAULT_CACHE_SIZE
1970: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
1980: 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 45  TE_DEFAULT_CACHE
1990: 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53  _SIZE.# define S
19a0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41  QLITE_DEFAULT_CA
19b0: 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a 23  CHE_SIZE  2000.#
19c0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
19d0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 4d  LITE_DEFAULT_TEM
19e0: 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 64  P_CACHE_SIZE.# d
19f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
1a00: 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 5f  AULT_TEMP_CACHE_
1a10: 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 66  SIZE  500.#endif
1a20: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ../*.** The defa
1a30: 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 72  ult number of fr
1a40: 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c 61  ames to accumula
1a50: 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69  te in the log fi
1a60: 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 65  le before.** che
1a70: 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 64  ckpointing the d
1a80: 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d  atabase in WAL m
1a90: 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ode..*/.#ifndef 
1aa0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57  SQLITE_DEFAULT_W
1ab0: 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e  AL_AUTOCHECKPOIN
1ac0: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  T.# define SQLIT
1ad0: 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55  E_DEFAULT_WAL_AU
1ae0: 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 30  TOCHECKPOINT  10
1af0: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1b00: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   The maximum num
1b10: 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20  ber of attached 
1b20: 64 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 73  databases.  This
1b30: 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
1b40: 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 54   0.** and 62.  T
1b50: 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  he upper bound o
1b60: 6e 20 36 32 20 69 73 20 62 65 63 61 75 73 65 20  n 62 is because 
1b70: 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  a 64-bit integer
1b80: 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 73   bitmap.** is us
1b90: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
1ba0: 20 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 20   track attached 
1bb0: 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 69  databases..*/.#i
1bc0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1bd0: 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 69  _ATTACHED.# defi
1be0: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54  ne SQLITE_MAX_AT
1bf0: 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 66  TACHED 10.#endif
1c00: 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78  .../*.** The max
1c10: 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 20  imum value of a 
1c20: 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 68  ?nnn wildcard th
1c30: 61 74 20 74 68 65 20 70 61 72 73 65 72 20 77 69  at the parser wi
1c40: 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 69  ll accept..*/.#i
1c50: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1c60: 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1c70: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1c80: 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
1c90: 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 0a  MBER 999.#endif.
1ca0: 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 65  ./* Maximum page
1cb0: 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 65   size.  The uppe
1cc0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 20  r bound on this 
1cd0: 76 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e 20  value is 65536. 
1ce0: 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a 2a   This a limit.**
1cf0: 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 20   imposed by the 
1d00: 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f 66  use of 16-bit of
1d10: 66 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 63  fsets within eac
1d20: 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 61  h page..**.** Ea
1d30: 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  rlier versions o
1d40: 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 64  f SQLite allowed
1d50: 20 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 61   the user to cha
1d60: 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 61  nge this value a
1d70: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t.** compile tim
1d80: 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c 6f  e. This is no lo
1d90: 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c 20  nger permitted, 
1da0: 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 74  on the grounds t
1db0: 68 61 74 20 69 74 20 63 72 65 61 74 65 73 0a 2a  hat it creates.*
1dc0: 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 74  * a library that
1dd0: 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 20   is technically 
1de0: 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 74  incompatible wit
1df0: 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 72  h an SQLite libr
1e00: 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  ary .** compiled
1e10: 20 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e   with a differen
1e20: 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 72  t limit. If a pr
1e30: 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 20  ocess operating 
1e40: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  on a database .*
1e50: 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 69  * with a page-si
1e60: 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 65  ze of 65536 byte
1e70: 73 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e 20  s crashes, then 
1e80: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 53  an instance of S
1e90: 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 6c  QLite .** compil
1ea0: 65 64 20 77 69 74 68 20 74 68 65 20 64 65 66 61  ed with the defa
1eb0: 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c 69  ult page-size li
1ec0: 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  mit will not be 
1ed0: 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b  able to rollback
1ee0: 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 64   .** the aborted
1ef0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
1f00: 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 6f  is could lead to
1f10: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
1f20: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  tion..*/.#ifdef 
1f30: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
1f40: 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 4c  SIZE.# undef SQL
1f50: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a  ITE_MAX_PAGE_SIZ
1f60: 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  E.#endif.#define
1f70: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45   SQLITE_MAX_PAGE
1f80: 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f 2a  _SIZE 65536.../*
1f90: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
1fa0: 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 61  size of a databa
1fb0: 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 6e  se page..*/.#ifn
1fc0: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55  def SQLITE_DEFAU
1fd0: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64  LT_PAGE_SIZE.# d
1fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
1ff0: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 31  AULT_PAGE_SIZE 1
2000: 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 53  024.#endif.#if S
2010: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41  QLITE_DEFAULT_PA
2020: 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f 4d  GE_SIZE>SQLITE_M
2030: 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 75  AX_PAGE_SIZE.# u
2040: 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41  ndef SQLITE_DEFA
2050: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20  ULT_PAGE_SIZE.# 
2060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
2070: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20  FAULT_PAGE_SIZE 
2080: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
2090: 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  SIZE.#endif../*.
20a0: 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 69  ** Ordinarily, i
20b0: 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 78  f no value is ex
20c0: 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 65  plicitly provide
20d0: 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 65  d, SQLite create
20e0: 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 77  s databases.** w
20f0: 69 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 51  ith page size SQ
2100: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47  LITE_DEFAULT_PAG
2110: 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 2c  E_SIZE. However,
2120: 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 69   based on certai
2130: 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 72  n.** device char
2140: 61 63 74 65 72 69 73 74 69 63 73 20 28 73 65 63  acteristics (sec
2150: 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 6f  tor-size and ato
2160: 6d 69 63 20 77 72 69 74 65 28 29 20 73 75 70 70  mic write() supp
2170: 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  ort),.** SQLite 
2180: 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 72  may choose a lar
2190: 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 20  ger value. This 
21a0: 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 20  constant is the 
21b0: 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a 2a  maximum value.**
21c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 6f   SQLite will cho
21d0: 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e 0a  ose on its own..
21e0: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
21f0: 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41  E_MAX_DEFAULT_PA
2200: 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65  GE_SIZE.# define
2210: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41   SQLITE_MAX_DEFA
2220: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 31  ULT_PAGE_SIZE 81
2230: 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51  92.#endif.#if SQ
2240: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54  LITE_MAX_DEFAULT
2250: 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54  _PAGE_SIZE>SQLIT
2260: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a  E_MAX_PAGE_SIZE.
2270: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  # undef SQLITE_M
2280: 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f  AX_DEFAULT_PAGE_
2290: 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51  SIZE.# define SQ
22a0: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54  LITE_MAX_DEFAULT
22b0: 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 54  _PAGE_SIZE SQLIT
22c0: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a  E_MAX_PAGE_SIZE.
22d0: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 4d  #endif.../*.** M
22e0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
22f0: 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 61   pages in one da
2300: 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
2310: 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c 6c  ** This is reall
2320: 79 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 75  y just the defau
2330: 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
2340: 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20   max_page_count 
2350: 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 20  pragma..** This 
2360: 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f 77  value can be low
2370: 65 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 29  ered (or raised)
2380: 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
2390: 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 6d  ng that the.** m
23a0: 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d 61  ax_page_count ma
23b0: 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  cro..*/.#ifndef 
23c0: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
23d0: 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 53  COUNT.# define S
23e0: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43  QLITE_MAX_PAGE_C
23f0: 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 0a  OUNT 1073741823.
2400: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61  #endif../*.** Ma
2410: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 6e  ximum length (in
2420: 20 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 70   bytes) of the p
2430: 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b 45  attern in a LIKE
2440: 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 72   or GLOB.** oper
2450: 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  ator..*/.#ifndef
2460: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45   SQLITE_MAX_LIKE
2470: 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 0a  _PATTERN_LENGTH.
2480: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2490: 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MAX_LIKE_PATTERN
24a0: 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 65  _LENGTH 50000.#e
24b0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 69  ndif../*.** Maxi
24c0: 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
24d0: 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
24e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 6c  ers..**.** A val
24f0: 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 68  ue of 1 means th
2500: 61 74 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  at a trigger pro
2510: 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 65  gram will not be
2520: 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 0a   able to itself.
2530: 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 67  ** fire any trig
2540: 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f 66  gers. A value of
2550: 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f   0 means that no
2560: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
2570: 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 79  s at all .** may
2580: 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a 2f   be executed..*/
2590: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
25a0: 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MAX_TRIGGER_DEPT
25b0: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  H.# define SQLIT
25c0: 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45  E_MAX_TRIGGER_DE
25d0: 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a  PTH 1000.#endif.
25e0: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
25f0: 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c 69   End of sqliteLi
2600: 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  mit.h **********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
2630: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
2640: 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72   Continuing wher
2650: 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e  e we left off in
2660: 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a   sqliteInt.h ***
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
2680: 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 69  ../* Disable nui
2690: 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 6f  sance warnings o
26a0: 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 6c  n Borland compil
26b0: 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e  ers */.#if defin
26c0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
26d0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 72  .#pragma warn -r
26e0: 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 6c  ch /* unreachabl
26f0: 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 6d  e code */.#pragm
2700: 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 43  a warn -ccc /* C
2710: 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 61  ondition is alwa
2720: 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65  ys true or false
2730: 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 6e   */.#pragma warn
2740: 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e 65   -aus /* Assigne
2750: 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 72  d value is never
2760: 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d 61   used */.#pragma
2770: 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 6f   warn -csu /* Co
2780: 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 61  mparing signed a
2790: 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a 23  nd unsigned */.#
27a0: 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 61  pragma warn -spa
27b0: 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 70   /* Suspicious p
27c0: 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 69  ointer arithmeti
27d0: 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20  c */.#endif../* 
27e0: 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f  Needed for vario
27f0: 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e  us definitions..
2800: 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 4e  . */.#ifndef _GN
2810: 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 6e  U_SOURCE.# defin
2820: 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65  e _GNU_SOURCE.#e
2830: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c  ndif../*.** Incl
2840: 75 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61  ude standard hea
2850: 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63  der files as nec
2860: 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66  essary.*/.#ifdef
2870: 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23   HAVE_STDINT_H.#
2880: 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e  include <stdint.
2890: 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66  h>.#endif.#ifdef
28a0: 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48   HAVE_INTTYPES_H
28b0: 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79  .#include <intty
28c0: 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f  pes.h>.#endif../
28d0: 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
28e0: 6e 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  ng macros are us
28f0: 65 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74  ed to cast point
2900: 65 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20  ers to integers 
2910: 61 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  and.** integers 
2920: 74 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68  to pointers.  Th
2930: 65 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69  e way you do thi
2940: 73 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  s varies from on
2950: 65 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f  e compiler.** to
2960: 20 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65   the next, so we
2970: 20 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20   have developed 
2980: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65  the following se
2990: 74 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65  t of #if stateme
29a0: 6e 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61  nts.** to genera
29b0: 74 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d  te appropriate m
29c0: 61 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65  acros for a wide
29d0: 20 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c   range of compil
29e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ers..**.** The c
29f0: 6f 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 61  orrect "ANSI" wa
2a00: 79 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20  y to do this is 
2a10: 74 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 74  to use the intpt
2a20: 72 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e  r_t type. .** Un
2a30: 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61  fortunately, tha
2a40: 74 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74  t typedef is not
2a50: 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c   available on al
2a60: 6c 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a  l compilers, or.
2a70: 2a 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 69  ** if it is avai
2a80: 6c 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72  lable, it requir
2a90: 65 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f  es an #include o
2aa0: 66 20 73 70 65 63 69 66 69 63 20 68 65 61 64 65  f specific heade
2ab0: 72 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20  rs.** that vary 
2ac0: 66 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65  from one machine
2ad0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a   to the next..**
2ae0: 0a 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30  .** Ticket #3860
2af0: 3a 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d  :  The llvm-gcc-
2b00: 34 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f  4.2 compiler fro
2b10: 6d 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f  m Apple chokes o
2b20: 6e 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a  n.** the ((void*
2b30: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29  )&((char*)0)[X])
2b40: 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74   construct.  But
2b50: 20 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20   MSVC chokes on 
2b60: 28 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a  ((void*)(X))..**
2b70: 20 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64   So we have to d
2b80: 65 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73  efine the macros
2b90: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61   in different wa
2ba0: 79 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ys depending on 
2bb0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e  the.** compiler.
2bc0: 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28  .*/.#if defined(
2bd0: 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f  __PTRDIFF_TYPE__
2be0: 29 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20  )  /* This case 
2bf0: 73 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20  should work for 
2c00: 47 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20  GCC */.# define 
2c10: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54  SQLITE_INT_TO_PT
2c20: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f  R(X)  ((void*)(_
2c30: 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29  _PTRDIFF_TYPE__)
2c40: 28 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51  (X)).# define SQ
2c50: 4c 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28  LITE_PTR_TO_INT(
2c60: 58 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52  X)  ((int)(__PTR
2c70: 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29  DIFF_TYPE__)(X))
2c80: 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28  .#elif !defined(
2c90: 5f 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20  __GNUC__)       
2ca0: 2f 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d  /* Works for com
2cb0: 70 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61  pilers other tha
2cc0: 6e 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69  n LLVM */.# defi
2cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f  ne SQLITE_INT_TO
2ce0: 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a  _PTR(X)  ((void*
2cf0: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29  )&((char*)0)[X])
2d00: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2d10: 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20  _PTR_TO_INT(X)  
2d20: 28 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58  ((int)(((char*)X
2d30: 29 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c  )-(char*)0)).#el
2d40: 69 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f  if defined(HAVE_
2d50: 53 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55  STDINT_H)   /* U
2d60: 73 65 20 74 68 69 73 20 63 61 73 65 20 69 66 20  se this case if 
2d70: 77 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 61  we have ANSI hea
2d80: 64 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65  ders */.# define
2d90: 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50   SQLITE_INT_TO_P
2da0: 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28  TR(X)  ((void*)(
2db0: 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20  intptr_t)(X)).# 
2dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54  define SQLITE_PT
2dd0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69  R_TO_INT(X)  ((i
2de0: 6e 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29  nt)(intptr_t)(X)
2df0: 29 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 20  ).#else         
2e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e10: 20 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20   /* Generates a 
2e20: 77 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74  warning - but it
2e30: 20 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f   always works */
2e40: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2e50: 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20  _INT_TO_PTR(X)  
2e60: 28 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64  ((void*)(X)).# d
2e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52  efine SQLITE_PTR
2e80: 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e  _TO_INT(X)  ((in
2e90: 74 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f  t)(X)).#endif../
2ea0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
2eb0: 54 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f  THREADSAFE macro
2ec0: 20 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 64   must be defined
2ed0: 20 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a   as 0, 1, or 2..
2ee0: 2a 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78  ** 0 means mutex
2ef0: 65 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74  es are permanent
2f00: 6c 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74  ly disable and t
2f10: 68 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65  he library is ne
2f20: 76 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66  ver.** threadsaf
2f30: 65 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20  e.  1 means the 
2f40: 6c 69 62 72 61 72 79 20 69 73 20 73 65 72 69 61  library is seria
2f50: 6c 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 74  lized which is t
2f60: 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65  he highest.** le
2f70: 76 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66  vel of threadsaf
2f80: 65 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68  ety.  2 means th
2f90: 65 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c 74  e libary is mult
2fa0: 69 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74  ithreaded - mult
2fb0: 69 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20  iple.** threads 
2fc0: 63 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61  can use SQLite a
2fd0: 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
2fe0: 20 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20   threads try to 
2ff0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
3000: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3010: 69 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  ion at the same 
3020: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65  time..**.** Olde
3030: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
3040: 4c 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74  Lite used an opt
3050: 69 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45  ional THREADSAFE
3060: 20 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75   macro..** We su
3070: 70 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c  pport that for l
3080: 65 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64  egacy..*/.#if !d
3090: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48  efined(SQLITE_TH
30a0: 52 45 41 44 53 41 46 45 29 0a 23 69 66 20 64 65  READSAFE).#if de
30b0: 66 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45  fined(THREADSAFE
30c0: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  ).# define SQLIT
30d0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 54 48 52  E_THREADSAFE THR
30e0: 45 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23 20  EADSAFE.#else.# 
30f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 48  define SQLITE_TH
3100: 52 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49 4d  READSAFE 1 /* IM
3110: 50 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30 39  P: R-07272-22309
3120: 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69   */.#endif.#endi
3130: 66 0a 0a 2f 2a 0a 2a 2a 20 50 6f 77 65 72 73 61  f../*.** Powersa
3140: 66 65 20 6f 76 65 72 77 72 69 74 65 20 69 73 20  fe overwrite is 
3150: 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
3160: 42 75 74 20 63 61 6e 20 62 65 20 74 75 72 6e 65  But can be turne
3170: 64 20 6f 66 66 20 75 73 69 6e 67 0a 2a 2a 20 74  d off using.** t
3180: 68 65 20 2d 44 53 51 4c 49 54 45 5f 50 4f 57 45  he -DSQLITE_POWE
3190: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 3d  RSAFE_OVERWRITE=
31a0: 30 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 6f  0 command-line o
31b0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ption..*/.#ifnde
31c0: 66 20 53 51 4c 49 54 45 5f 50 4f 57 45 52 53 41  f SQLITE_POWERSA
31d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 0a 23 20 64  FE_OVERWRITE.# d
31e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 4f 57  efine SQLITE_POW
31f0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
3200: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a   1.#endif../*.**
3210: 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46 41   The SQLITE_DEFA
3220: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 20 6d 61  ULT_MEMSTATUS ma
3230: 63 72 6f 20 6d 75 73 74 20 62 65 20 64 65 66 69  cro must be defi
3240: 6e 65 64 20 61 73 20 65 69 74 68 65 72 20 30 20  ned as either 0 
3250: 6f 72 20 31 2e 0a 2a 2a 20 49 74 20 64 65 74 65  or 1..** It dete
3260: 72 6d 69 6e 65 73 20 77 68 65 74 68 65 72 20 6f  rmines whether o
3270: 72 20 6e 6f 74 20 74 68 65 20 66 65 61 74 75 72  r not the featur
3280: 65 73 20 72 65 6c 61 74 65 64 20 74 6f 20 0a 2a  es related to .*
3290: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
32a0: 4d 45 4d 53 54 41 54 55 53 20 61 72 65 20 61 76  MEMSTATUS are av
32b0: 61 69 6c 61 62 6c 65 20 62 79 20 64 65 66 61 75  ailable by defau
32c0: 6c 74 20 6f 72 20 6e 6f 74 2e 20 54 68 69 73 20  lt or not. This 
32d0: 76 61 6c 75 65 20 63 61 6e 0a 2a 2a 20 62 65 20  value can.** be 
32e0: 6f 76 65 72 72 69 64 64 65 6e 20 61 74 20 72 75  overridden at ru
32f0: 6e 74 69 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ntime using the 
3300: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
3310: 20 41 50 49 2e 0a 2a 2f 0a 23 69 66 20 21 64 65   API..*/.#if !de
3320: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 46  fined(SQLITE_DEF
3330: 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 29 0a  AULT_MEMSTATUS).
3340: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
3350: 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
3360: 53 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  S 1.#endif../*.*
3370: 2a 20 45 78 61 63 74 6c 79 20 6f 6e 65 20 6f 66  * Exactly one of
3380: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d   the following m
3390: 61 63 72 6f 73 20 6d 75 73 74 20 62 65 20 64 65  acros must be de
33a0: 66 69 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  fined in order t
33b0: 6f 0a 2a 2a 20 73 70 65 63 69 66 79 20 77 68 69  o.** specify whi
33c0: 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ch memory alloca
33d0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 74  tion subsystem t
33e0: 6f 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 20 20 20  o use..**.**    
33f0: 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d   SQLITE_SYSTEM_M
3400: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 20 2f  ALLOC          /
3410: 2f 20 55 73 65 20 6e 6f 72 6d 61 6c 20 73 79 73  / Use normal sys
3420: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 20  tem malloc().** 
3430: 20 20 20 20 53 51 4c 49 54 45 5f 57 49 4e 33 32      SQLITE_WIN32
3440: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20  _MALLOC         
3450: 20 20 2f 2f 20 55 73 65 20 57 69 6e 33 32 20 6e    // Use Win32 n
3460: 61 74 69 76 65 20 68 65 61 70 20 41 50 49 0a 2a  ative heap API.*
3470: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4d 45 4d  *     SQLITE_MEM
3480: 44 45 42 55 47 20 20 20 20 20 20 20 20 20 20 20  DEBUG           
3490: 20 20 20 20 2f 2f 20 44 65 62 75 67 67 69 6e 67      // Debugging
34a0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 79 73 74   version of syst
34b0: 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a 2a  em malloc().**.*
34c0: 2a 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69 66  * On Windows, if
34d0: 20 74 68 65 20 53 51 4c 49 54 45 5f 57 49 4e 33   the SQLITE_WIN3
34e0: 32 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41 54  2_MALLOC_VALIDAT
34f0: 45 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e  E macro is defin
3500: 65 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61 73  ed and the.** as
3510: 73 65 72 74 28 29 20 6d 61 63 72 6f 20 69 73 20  sert() macro is 
3520: 65 6e 61 62 6c 65 64 2c 20 65 61 63 68 20 63 61  enabled, each ca
3530: 6c 6c 20 69 6e 74 6f 20 74 68 65 20 57 69 6e 33  ll into the Win3
3540: 32 20 6e 61 74 69 76 65 20 68 65 61 70 20 73 75  2 native heap su
3550: 62 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c 20  bsystem.** will 
3560: 63 61 75 73 65 20 48 65 61 70 56 61 6c 69 64 61  cause HeapValida
3570: 74 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e  te to be called.
3580: 20 20 49 66 20 68 65 61 70 20 76 61 6c 69 64 61    If heap valida
3590: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69 6c  tion should fail
35a0: 2c 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69 6f  , an.** assertio
35b0: 6e 20 77 69 6c 6c 20 62 65 20 74 72 69 67 67 65  n will be trigge
35c0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74  red..**.** (Hist
35d0: 6f 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54 68  orical note:  Th
35e0: 65 72 65 20 75 73 65 64 20 74 6f 20 62 65 20 73  ere used to be s
35f0: 65 76 65 72 61 6c 20 6f 74 68 65 72 20 6f 70 74  everal other opt
3600: 69 6f 6e 73 2c 20 62 75 74 20 77 65 27 76 65 0a  ions, but we've.
3610: 2a 2a 20 70 61 72 65 64 20 69 74 20 64 6f 77 6e  ** pared it down
3620: 20 74 6f 20 6a 75 73 74 20 74 68 65 73 65 20 74   to just these t
3630: 68 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66 20  hree.).**.** If 
3640: 6e 6f 6e 65 20 6f 66 20 74 68 65 20 61 62 6f 76  none of the abov
3650: 65 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  e are defined, t
3660: 68 65 6e 20 73 65 74 20 53 51 4c 49 54 45 5f 53  hen set SQLITE_S
3670: 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73 0a  YSTEM_MALLOC as.
3680: 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 0a  ** the default..
3690: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53  */.#if defined(S
36a0: 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c  QLITE_SYSTEM_MAL
36b0: 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 53 51 4c  LOC)+defined(SQL
36c0: 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43  ITE_WIN32_MALLOC
36d0: 29 2b 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45  )+defined(SQLITE
36e0: 5f 4d 45 4d 44 45 42 55 47 29 3e 31 0a 23 20 65  _MEMDEBUG)>1.# e
36f0: 72 72 6f 72 20 22 41 74 20 6d 6f 73 74 20 6f 6e  rror "At most on
3700: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
3710: 6e 67 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ng compile-time 
3720: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
3730: 74 69 6f 6e 73 5c 0a 20 69 73 20 61 6c 6c 6f 77  tions\. is allow
3740: 73 3a 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d  s: SQLITE_SYSTEM
3750: 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 45 5f  _MALLOC, SQLITE_
3760: 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51  WIN32_MALLOC, SQ
3770: 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 22 0a 23  LITE_MEMDEBUG".#
3780: 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69 6e 65  endif.#if define
3790: 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f  d(SQLITE_SYSTEM_
37a0: 4d 41 4c 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28  MALLOC)+defined(
37b0: 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
37c0: 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 53 51 4c  LOC)+defined(SQL
37d0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d 3d 30  ITE_MEMDEBUG)==0
37e0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
37f0: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 31  _SYSTEM_MALLOC 1
3800: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49  .#endif../*.** I
3810: 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f  f SQLITE_MALLOC_
3820: 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20 6e 6f  SOFT_LIMIT is no
3830: 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 79  t zero, then try
3840: 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a 2a 20   to keep the.** 
3850: 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  sizes of memory 
3860: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65 6c 6f  allocations belo
3870: 77 20 74 68 69 73 20 76 61 6c 75 65 20 77 68 65  w this value whe
3880: 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2f 0a  re possible..*/.
3890: 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c  #if !defined(SQL
38a0: 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f  ITE_MALLOC_SOFT_
38b0: 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e 65 20  LIMIT).# define 
38c0: 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f  SQLITE_MALLOC_SO
38d0: 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a 23 65  FT_LIMIT 1024.#e
38e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65 20 6e  ndif../*.** We n
38f0: 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20 5f 58  eed to define _X
3900: 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73 20 66  OPEN_SOURCE as f
3910: 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65 72 20  ollows in order 
3920: 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72 65 63  to enable.** rec
3930: 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 20 6f  ursive mutexes o
3940: 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79 73 74  n most Unix syst
3950: 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20 4f 53  ems.  But Mac OS
3960: 20 58 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e   X is different.
3970: 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e 5f 53  .** The _XOPEN_S
3980: 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63 61 75  OURCE define cau
3990: 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f 72  ses problems for
39a0: 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61 72 65   Mac OS X we are
39b0: 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69 74 20   told,.** so it 
39c0: 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 72 65  is omitted there
39d0: 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
39e0: 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74 65 72  673..**.** Later
39f0: 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74 20 5f   we learn that _
3a00: 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69 73 20  XOPEN_SOURCE is 
3a10: 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f 72 72  poorly or incorr
3a20: 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ectly.** impleme
3a30: 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73 79 73  nted on some sys
3a40: 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61 76 6f  tems.  So we avo
3a50: 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74 20 61  id defining it a
3a60: 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74 20 69  t all.** if it i
3a70: 73 20 61 6c 72 65 61 64 79 20 64 65 66 69 6e 65  s already define
3a80: 64 20 6f 72 20 69 66 20 69 74 20 69 73 20 75 6e  d or if it is un
3a90: 6e 65 65 64 65 64 20 62 65 63 61 75 73 65 20 77  needed because w
3aa0: 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64 6f 69  e are.** not doi
3ab0: 6e 67 20 61 20 74 68 72 65 61 64 73 61 66 65 20  ng a threadsafe 
3ac0: 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74 20 23  build.  Ticket #
3ad0: 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2681..**.** See 
3ae0: 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32 37 34  also ticket #274
3af0: 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e  1..*/.#if !defin
3b00: 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45  ed(_XOPEN_SOURCE
3b10: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 5f  ) && !defined(__
3b20: 44 41 52 57 49 4e 5f 5f 29 20 26 26 20 21 64 65  DARWIN__) && !de
3b30: 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45 5f 5f 29  fined(__APPLE__)
3b40: 20 26 26 20 53 51 4c 49 54 45 5f 54 48 52 45 41   && SQLITE_THREA
3b50: 44 53 41 46 45 0a 23 20 20 64 65 66 69 6e 65 20  DSAFE.#  define 
3b60: 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 35 30  _XOPEN_SOURCE 50
3b70: 30 20 20 2f 2a 20 4e 65 65 64 65 64 20 74 6f 20  0  /* Needed to 
3b80: 65 6e 61 62 6c 65 20 70 74 68 72 65 61 64 20 72  enable pthread r
3b90: 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73  ecursive mutexes
3ba0: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a   */.#endif../*.*
3bb0: 2a 20 54 68 65 20 54 43 4c 20 68 65 61 64 65 72  * The TCL header
3bc0: 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65 65 64 65  s are only neede
3bd0: 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67  d when compiling
3be0: 20 74 68 65 20 54 43 4c 20 62 69 6e 64 69 6e 67   the TCL binding
3bf0: 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  s..*/.#if define
3c00: 64 28 53 51 4c 49 54 45 5f 54 43 4c 29 20 7c 7c  d(SQLITE_TCL) ||
3c10: 20 64 65 66 69 6e 65 64 28 54 43 4c 53 48 29 0a   defined(TCLSH).
3c20: 23 20 69 6e 63 6c 75 64 65 20 3c 74 63 6c 2e 68  # include <tcl.h
3c30: 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  >.#endif../*.** 
3c40: 4e 44 45 42 55 47 20 61 6e 64 20 53 51 4c 49 54  NDEBUG and SQLIT
3c50: 45 5f 44 45 42 55 47 20 61 72 65 20 6f 70 70 6f  E_DEBUG are oppo
3c60: 73 69 74 65 73 2e 20 20 49 74 20 73 68 6f 75 6c  sites.  It shoul
3c70: 64 20 61 6c 77 61 79 73 20 62 65 20 74 72 75 65  d always be true
3c80: 20 74 68 61 74 0a 2a 2a 20 64 65 66 69 6e 65 64   that.** defined
3c90: 28 4e 44 45 42 55 47 29 3d 3d 21 64 65 66 69 6e  (NDEBUG)==!defin
3ca0: 65 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29  ed(SQLITE_DEBUG)
3cb0: 2e 20 20 49 66 20 74 68 69 73 20 69 73 20 6e 6f  .  If this is no
3cc0: 74 20 63 75 72 72 65 6e 74 6c 79 20 74 72 75 65  t currently true
3cd0: 2c 0a 2a 2a 20 6d 61 6b 65 20 69 74 20 74 72 75  ,.** make it tru
3ce0: 65 20 62 79 20 64 65 66 69 6e 69 6e 67 20 6f 72  e by defining or
3cf0: 20 75 6e 64 65 66 69 6e 69 6e 67 20 4e 44 45 42   undefining NDEB
3d00: 55 47 2e 0a 2a 2a 0a 2a 2a 20 53 65 74 74 69 6e  UG..**.** Settin
3d10: 67 20 4e 44 45 42 55 47 20 6d 61 6b 65 73 20 74  g NDEBUG makes t
3d20: 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c 65 72 20  he code smaller 
3d30: 61 6e 64 20 72 75 6e 20 66 61 73 74 65 72 20 62  and run faster b
3d40: 79 20 64 69 73 61 62 6c 69 6e 67 20 74 68 65 0a  y disabling the.
3d50: 2a 2a 20 6e 75 6d 62 65 72 20 61 73 73 65 72 74  ** number assert
3d60: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
3d70: 20 74 68 65 20 63 6f 64 65 2e 20 20 53 6f 20 77   the code.  So w
3d80: 65 20 77 61 6e 74 20 74 68 65 20 64 65 66 61 75  e want the defau
3d90: 6c 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20  lt action.** to 
3da0: 62 65 20 66 6f 72 20 4e 44 45 42 55 47 20 74 6f  be for NDEBUG to
3db0: 20 62 65 20 73 65 74 20 61 6e 64 20 4e 44 45 42   be set and NDEB
3dc0: 55 47 20 74 6f 20 62 65 20 75 6e 64 65 66 69 6e  UG to be undefin
3dd0: 65 64 20 6f 6e 6c 79 20 69 66 20 53 51 4c 49 54  ed only if SQLIT
3de0: 45 5f 44 45 42 55 47 0a 2a 2a 20 69 73 20 73 65  E_DEBUG.** is se
3df0: 74 2e 20 20 54 68 75 73 20 4e 44 45 42 55 47 20  t.  Thus NDEBUG 
3e00: 62 65 63 6f 6d 65 73 20 61 6e 20 6f 70 74 2d 69  becomes an opt-i
3e10: 6e 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 6e  n rather than an
3e20: 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66 65 61 74   opt-out.** feat
3e30: 75 72 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66  ure..*/.#if !def
3e40: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 26 26 20  ined(NDEBUG) && 
3e50: 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f  !defined(SQLITE_
3e60: 44 45 42 55 47 29 20 0a 23 20 64 65 66 69 6e 65  DEBUG) .# define
3e70: 20 4e 44 45 42 55 47 20 31 0a 23 65 6e 64 69 66   NDEBUG 1.#endif
3e80: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 4e 44 45  .#if defined(NDE
3e90: 42 55 47 29 20 26 26 20 64 65 66 69 6e 65 64 28  BUG) && defined(
3ea0: 53 51 4c 49 54 45 5f 44 45 42 55 47 29 0a 23 20  SQLITE_DEBUG).# 
3eb0: 75 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 65 6e  undef NDEBUG.#en
3ec0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  dif../*.** The t
3ed0: 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20  estcase() macro 
3ee0: 69 73 20 75 73 65 64 20 74 6f 20 61 69 64 20 69  is used to aid i
3ef0: 6e 20 63 6f 76 65 72 61 67 65 20 74 65 73 74 69  n coverage testi
3f00: 6e 67 2e 20 20 57 68 65 6e 20 0a 2a 2a 20 64 6f  ng.  When .** do
3f10: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73  ing coverage tes
3f20: 74 69 6e 67 2c 20 74 68 65 20 63 6f 6e 64 69 74  ting, the condit
3f30: 69 6f 6e 20 69 6e 73 69 64 65 20 74 68 65 20 61  ion inside the a
3f40: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 65  rgument to.** te
3f50: 73 74 63 61 73 65 28 29 20 6d 75 73 74 20 62 65  stcase() must be
3f60: 20 65 76 61 6c 75 61 74 65 64 20 62 6f 74 68 20   evaluated both 
3f70: 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 20 69  true and false i
3f80: 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 67 65  n order to.** ge
3f90: 74 20 66 75 6c 6c 20 62 72 61 6e 63 68 20 63 6f  t full branch co
3fa0: 76 65 72 61 67 65 2e 20 20 54 68 65 20 74 65 73  verage.  The tes
3fb0: 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20 69 73  tcase() macro is
3fc0: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 74 6f 20   inserted.** to 
3fd0: 68 65 6c 70 20 65 6e 73 75 72 65 20 61 64 65 71  help ensure adeq
3fe0: 75 61 74 65 20 74 65 73 74 20 63 6f 76 65 72 61  uate test covera
3ff0: 67 65 20 69 6e 20 70 6c 61 63 65 73 20 77 68 65  ge in places whe
4000: 72 65 20 73 69 6d 70 6c 65 0a 2a 2a 20 63 6f 6e  re simple.** con
4010: 64 69 74 69 6f 6e 2f 64 65 63 69 73 69 6f 6e 20  dition/decision 
4020: 63 6f 76 65 72 61 67 65 20 69 73 20 69 6e 61 64  coverage is inad
4030: 65 71 75 61 74 65 2e 20 20 46 6f 72 20 65 78 61  equate.  For exa
4040: 6d 70 6c 65 2c 20 74 65 73 74 63 61 73 65 28 29  mple, testcase()
4050: 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
4060: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 62 6f 75  to make sure bou
4070: 6e 64 61 72 79 20 76 61 6c 75 65 73 20 61 72 65  ndary values are
4080: 20 74 65 73 74 65 64 2e 20 20 46 6f 72 0a 2a 2a   tested.  For.**
4090: 20 62 69 74 6d 61 73 6b 20 74 65 73 74 73 2c 20   bitmask tests, 
40a0: 74 65 73 74 63 61 73 65 28 29 20 63 61 6e 20 62  testcase() can b
40b0: 65 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73  e used to make s
40c0: 75 72 65 20 65 61 63 68 20 62 69 74 0a 2a 2a 20  ure each bit.** 
40d0: 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 61  is significant a
40e0: 6e 64 20 75 73 65 64 20 61 74 20 6c 65 61 73 74  nd used at least
40f0: 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 77 69 74 63   once.  On switc
4100: 68 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  h statements.** 
4110: 77 68 65 72 65 20 6d 75 6c 74 69 70 6c 65 20 63  where multiple c
4120: 61 73 65 73 20 67 6f 20 74 6f 20 74 68 65 20 73  ases go to the s
4130: 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20 63 6f 64  ame block of cod
4140: 65 2c 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a  e, testcase().**
4150: 20 63 61 6e 20 69 6e 73 75 72 65 20 74 68 61 74   can insure that
4160: 20 61 6c 6c 20 63 61 73 65 73 20 61 72 65 20 65   all cases are e
4170: 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2f 0a  valuated..**.*/.
4180: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 43 4f  #ifdef SQLITE_CO
4190: 56 45 52 41 47 45 5f 54 45 53 54 0a 53 51 4c 49  VERAGE_TEST.SQLI
41a0: 54 45 5f 50 52 49 56 41 54 45 20 20 20 76 6f 69  TE_PRIVATE   voi
41b0: 64 20 73 71 6c 69 74 65 33 43 6f 76 65 72 61 67  d sqlite3Coverag
41c0: 65 28 69 6e 74 29 3b 0a 23 20 64 65 66 69 6e 65  e(int);.# define
41d0: 20 74 65 73 74 63 61 73 65 28 58 29 20 20 69 66   testcase(X)  if
41e0: 28 20 58 20 29 7b 20 73 71 6c 69 74 65 33 43 6f  ( X ){ sqlite3Co
41f0: 76 65 72 61 67 65 28 5f 5f 4c 49 4e 45 5f 5f 29  verage(__LINE__)
4200: 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  ; }.#else.# defi
4210: 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 0a 23  ne testcase(X).#
4220: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
4230: 20 54 45 53 54 4f 4e 4c 59 20 6d 61 63 72 6f 20   TESTONLY macro 
4240: 69 73 20 75 73 65 64 20 74 6f 20 65 6e 63 6c 6f  is used to enclo
4250: 73 65 20 76 61 72 69 61 62 6c 65 20 64 65 63 6c  se variable decl
4260: 61 72 61 74 69 6f 6e 73 20 6f 72 0a 2a 2a 20 6f  arations or.** o
4270: 74 68 65 72 20 62 69 74 73 20 6f 66 20 63 6f 64  ther bits of cod
4280: 65 20 74 68 61 74 20 61 72 65 20 6e 65 65 64 65  e that are neede
4290: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 74 68 65  d to support the
42a0: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 77 69   arguments.** wi
42b0: 74 68 69 6e 20 74 65 73 74 63 61 73 65 28 29 20  thin testcase() 
42c0: 61 6e 64 20 61 73 73 65 72 74 28 29 20 6d 61 63  and assert() mac
42d0: 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66  ros..*/.#if !def
42e0: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 7c 7c 20  ined(NDEBUG) || 
42f0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 43  defined(SQLITE_C
4300: 4f 56 45 52 41 47 45 5f 54 45 53 54 29 0a 23 20  OVERAGE_TEST).# 
4310: 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28  define TESTONLY(
4320: 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65  X)  X.#else.# de
4330: 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28 58 29  fine TESTONLY(X)
4340: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 53  .#endif../*.** S
4350: 6f 6d 65 74 69 6d 65 73 20 77 65 20 6e 65 65 64  ometimes we need
4360: 20 61 20 73 6d 61 6c 6c 20 61 6d 6f 75 6e 74 20   a small amount 
4370: 6f 66 20 63 6f 64 65 20 73 75 63 68 20 61 73 20  of code such as 
4380: 61 20 76 61 72 69 61 62 6c 65 20 69 6e 69 74 69  a variable initi
4390: 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  alization.** to 
43a0: 73 65 74 75 70 20 66 6f 72 20 61 20 6c 61 74 65  setup for a late
43b0: 72 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  r assert() state
43c0: 6d 65 6e 74 2e 20 20 57 65 20 64 6f 20 6e 6f 74  ment.  We do not
43d0: 20 77 61 6e 74 20 74 68 69 73 20 63 6f 64 65 20   want this code 
43e0: 74 6f 0a 2a 2a 20 61 70 70 65 61 72 20 77 68 65  to.** appear whe
43f0: 6e 20 61 73 73 65 72 74 28 29 20 69 73 20 64 69  n assert() is di
4400: 73 61 62 6c 65 64 2e 20 20 54 68 65 20 66 6f 6c  sabled.  The fol
4410: 6c 6f 77 69 6e 67 20 6d 61 63 72 6f 20 69 73 20  lowing macro is 
4420: 74 68 65 72 65 66 6f 72 65 0a 2a 2a 20 75 73 65  therefore.** use
4430: 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 61  d to contain tha
4440: 74 20 73 65 74 75 70 20 63 6f 64 65 2e 20 20 54  t setup code.  T
4450: 68 65 20 22 56 56 41 22 20 61 63 72 6f 6e 79 6d  he "VVA" acronym
4460: 20 73 74 61 6e 64 73 20 66 6f 72 0a 2a 2a 20 22   stands for.** "
4470: 56 65 72 69 66 69 63 61 74 69 6f 6e 2c 20 56 61  Verification, Va
4480: 6c 69 64 61 74 69 6f 6e 2c 20 61 6e 64 20 41 63  lidation, and Ac
4490: 63 72 65 64 69 74 61 74 69 6f 6e 22 2e 20 20 49  creditation".  I
44a0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
44b0: 68 65 0a 2a 2a 20 63 6f 64 65 20 77 69 74 68 69  he.** code withi
44c0: 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 20 77 69 6c  n VVA_ONLY() wil
44d0: 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 75 72 69 6e  l only run durin
44e0: 67 20 76 65 72 69 66 69 63 61 74 69 6f 6e 20 70  g verification p
44f0: 72 6f 63 65 73 73 65 73 2e 0a 2a 2f 0a 23 69 66  rocesses..*/.#if
4500: 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 20 64 65  ndef NDEBUG.# de
4510: 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29  fine VVA_ONLY(X)
4520: 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65 66 69    X.#else.# defi
4530: 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29 0a 23  ne VVA_ONLY(X).#
4540: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
4550: 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45   ALWAYS and NEVE
4560: 52 20 6d 61 63 72 6f 73 20 73 75 72 72 6f 75 6e  R macros surroun
4570: 64 20 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73  d boolean expres
4580: 73 69 6f 6e 73 20 77 68 69 63 68 20 0a 2a 2a 20  sions which .** 
4590: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
45a0: 61 6c 77 61 79 73 20 62 65 20 74 72 75 65 20 6f  always be true o
45b0: 72 20 66 61 6c 73 65 2c 20 72 65 73 70 65 63 74  r false, respect
45c0: 69 76 65 6c 79 2e 20 20 53 75 63 68 0a 2a 2a 20  ively.  Such.** 
45d0: 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 75 6c  expressions coul
45e0: 64 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f  d be omitted fro
45f0: 6d 20 74 68 65 20 63 6f 64 65 20 63 6f 6d 70 6c  m the code compl
4600: 65 74 65 6c 79 2e 20 20 42 75 74 20 74 68 65 79  etely.  But they
4610: 0a 2a 2a 20 61 72 65 20 69 6e 63 6c 75 64 65 64  .** are included
4620: 20 69 6e 20 61 20 66 65 77 20 63 61 73 65 73 20   in a few cases 
4630: 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 68 61  in order to enha
4640: 6e 63 65 20 74 68 65 20 72 65 73 69 6c 69 65 6e  nce the resilien
4650: 63 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  ce.** of SQLite 
4660: 74 6f 20 75 6e 65 78 70 65 63 74 65 64 20 62 65  to unexpected be
4670: 68 61 76 69 6f 72 20 2d 20 74 6f 20 6d 61 6b 65  havior - to make
4680: 20 74 68 65 20 63 6f 64 65 20 22 73 65 6c 66 2d   the code "self-
4690: 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 6f 72 20 22  healing".** or "
46a0: 64 75 63 74 69 6c 65 22 20 72 61 74 68 65 72 20  ductile" rather 
46b0: 74 68 61 6e 20 62 65 69 6e 67 20 22 62 72 69 74  than being "brit
46c0: 74 6c 65 22 20 61 6e 64 20 63 72 61 73 68 69 6e  tle" and crashin
46d0: 67 20 61 74 20 74 68 65 20 66 69 72 73 74 0a 2a  g at the first.*
46e0: 2a 20 68 69 6e 74 20 6f 66 20 75 6e 70 6c 61 6e  * hint of unplan
46f0: 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
4700: 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
4710: 64 73 2c 20 41 4c 57 41 59 53 20 61 6e 64 20 4e  ds, ALWAYS and N
4720: 45 56 45 52 20 61 72 65 20 61 64 64 65 64 20 66  EVER are added f
4730: 6f 72 20 64 65 66 65 6e 73 69 76 65 20 63 6f 64  or defensive cod
4740: 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 64 6f  e..**.** When do
4750: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73  ing coverage tes
4760: 74 69 6e 67 20 41 4c 57 41 59 53 20 61 6e 64 20  ting ALWAYS and 
4770: 4e 45 56 45 52 20 61 72 65 20 68 61 72 64 2d 63  NEVER are hard-c
4780: 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 65 20 74 72  oded to.** be tr
4790: 75 65 20 61 6e 64 20 66 61 6c 73 65 20 73 6f 20  ue and false so 
47a0: 74 68 61 74 20 74 68 65 20 75 6e 72 65 61 63 68  that the unreach
47b0: 61 62 6c 65 20 63 6f 64 65 20 74 68 65 6e 20 73  able code then s
47c0: 70 65 63 69 66 79 20 77 69 6c 6c 0a 2a 2a 20 6e  pecify will.** n
47d0: 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 61 73  ot be counted as
47e0: 20 75 6e 74 65 73 74 65 64 20 63 6f 64 65 2e 0a   untested code..
47f0: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53  */.#if defined(S
4800: 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54  QLITE_COVERAGE_T
4810: 45 53 54 29 0a 23 20 64 65 66 69 6e 65 20 41 4c  EST).# define AL
4820: 57 41 59 53 28 58 29 20 20 20 20 20 20 28 31 29  WAYS(X)      (1)
4830: 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 28  .# define NEVER(
4840: 58 29 20 20 20 20 20 20 20 28 30 29 0a 23 65 6c  X)       (0).#el
4850: 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42  if !defined(NDEB
4860: 55 47 29 0a 23 20 64 65 66 69 6e 65 20 41 4c 57  UG).# define ALW
4870: 41 59 53 28 58 29 20 20 20 20 20 20 28 28 58 29  AYS(X)      ((X)
4880: 3f 31 3a 28 61 73 73 65 72 74 28 30 29 2c 30 29  ?1:(assert(0),0)
4890: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52  ).# define NEVER
48a0: 28 58 29 20 20 20 20 20 20 20 28 28 58 29 3f 28  (X)       ((X)?(
48b0: 61 73 73 65 72 74 28 30 29 2c 31 29 3a 30 29 0a  assert(0),1):0).
48c0: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 41  #else.# define A
48d0: 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28 58  LWAYS(X)      (X
48e0: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52  ).# define NEVER
48f0: 28 58 29 20 20 20 20 20 20 20 28 58 29 0a 23 65  (X)       (X).#e
4900: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75  ndif../*.** Retu
4910: 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  rn true (non-zer
4920: 6f 29 20 69 66 20 74 68 65 20 69 6e 70 75 74 20  o) if the input 
4930: 69 73 20 61 20 69 6e 74 65 67 65 72 20 74 68 61  is a integer tha
4940: 74 20 69 73 20 74 6f 6f 20 6c 61 72 67 65 0a 2a  t is too large.*
4950: 2a 20 74 6f 20 66 69 74 20 69 6e 20 33 32 2d 62  * to fit in 32-b
4960: 69 74 73 2e 20 20 54 68 69 73 20 6d 61 63 72 6f  its.  This macro
4970: 20 69 73 20 75 73 65 64 20 69 6e 73 69 64 65 20   is used inside 
4980: 6f 66 20 76 61 72 69 6f 75 73 20 74 65 73 74 63  of various testc
4990: 61 73 65 28 29 0a 2a 2a 20 6d 61 63 72 6f 73 20  ase().** macros 
49a0: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 77  to verify that w
49b0: 65 20 68 61 76 65 20 74 65 73 74 65 64 20 53 51  e have tested SQ
49c0: 4c 69 74 65 20 66 6f 72 20 6c 61 72 67 65 2d 66  Lite for large-f
49d0: 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a  ile support..*/.
49e0: 23 64 65 66 69 6e 65 20 49 53 5f 42 49 47 5f 49  #define IS_BIG_I
49f0: 4e 54 28 58 29 20 20 28 28 28 58 29 26 7e 28 69  NT(X)  (((X)&~(i
4a00: 36 34 29 30 78 66 66 66 66 66 66 66 66 29 21 3d  64)0xffffffff)!=
4a10: 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61  0)../*.** The ma
4a20: 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 28 29 20 69  cro unlikely() i
4a30: 73 20 61 20 68 69 6e 74 20 74 68 61 74 20 73 75  s a hint that su
4a40: 72 72 6f 75 6e 64 73 20 61 20 62 6f 6f 6c 65 61  rrounds a boolea
4a50: 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
4a60: 74 68 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20  that is usually 
4a70: 66 61 6c 73 65 2e 20 20 4d 61 63 72 6f 20 6c 69  false.  Macro li
4a80: 6b 65 6c 79 28 29 20 73 75 72 72 6f 75 6e 64 73  kely() surrounds
4a90: 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 65 78  .** a boolean ex
4aa0: 70 72 65 73 73 69 6f 6e 20 74 68 61 74 20 69 73  pression that is
4ab0: 20 75 73 75 61 6c 6c 79 20 74 72 75 65 2e 20 20   usually true.  
4ac0: 47 43 43 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  GCC is able to.*
4ad0: 2a 20 75 73 65 20 74 68 65 73 65 20 68 69 6e 74  * use these hint
4ae0: 73 20 74 6f 20 67 65 6e 65 72 61 74 65 20 62 65  s to generate be
4af0: 74 74 65 72 20 63 6f 64 65 2c 20 73 6f 6d 65 74  tter code, somet
4b00: 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66  imes..*/.#if def
4b10: 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26  ined(__GNUC__) &
4b20: 26 20 30 0a 23 20 64 65 66 69 6e 65 20 6c 69 6b  & 0.# define lik
4b30: 65 6c 79 28 58 29 20 20 20 20 5f 5f 62 75 69 6c  ely(X)    __buil
4b40: 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 31  tin_expect((X),1
4b50: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b  ).# define unlik
4b60: 65 6c 79 28 58 29 20 20 5f 5f 62 75 69 6c 74 69  ely(X)  __builti
4b70: 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 30 29 0a  n_expect((X),0).
4b80: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 6c  #else.# define l
4b90: 69 6b 65 6c 79 28 58 29 20 20 20 20 21 21 28 58  ikely(X)    !!(X
4ba0: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b  ).# define unlik
4bb0: 65 6c 79 28 58 29 20 20 21 21 28 58 29 0a 23 65  ely(X)  !!(X).#e
4bc0: 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  ndif../*********
4bd0: 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71  ***** Include sq
4be0: 6c 69 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d  lite3.h in the m
4bf0: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49  iddle of sqliteI
4c00: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
4c10: 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****/./*********
4c20: 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65  ***** Begin file
4c30: 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a   sqlite3.h *****
4c40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4c50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4c60: 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31  ****/./*.** 2001
4c70: 20 53 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a   September 15.**
4c80: 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64  .** The author d
4c90: 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67  isclaims copyrig
4ca0: 68 74 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63  ht to this sourc
4cb0: 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63  e code.  In plac
4cc0: 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20  e of.** a legal 
4cd0: 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 69 73 20  notice, here is 
4ce0: 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a  a blessing:.**.*
4cf0: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20  *    May you do 
4d00: 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69  good and not evi
4d10: 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  l..**    May you
4d20: 20 66 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73   find forgivenes
4d30: 73 20 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61  s for yourself a
4d40: 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72  nd forgive other
4d50: 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  s..**    May you
4d60: 20 73 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e   share freely, n
4d70: 65 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65  ever taking more
4d80: 20 74 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a   than you give..
4d90: 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **.*************
4da0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4db0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4dc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4dd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20  ************.** 
4de0: 54 68 69 73 20 68 65 61 64 65 72 20 66 69 6c 65  This header file
4df0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
4e00: 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20  erface that the 
4e10: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a  SQLite library.*
4e20: 2a 20 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c  * presents to cl
4e30: 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20  ient programs.  
4e40: 49 66 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c  If a C-function,
4e50: 20 73 74 72 75 63 74 75 72 65 2c 20 64 61 74 61   structure, data
4e60: 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73  type,.** or cons
4e70: 74 61 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20  tant definition 
4e80: 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
4e90: 69 6e 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68  in this file, th
4ea0: 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  en it is.** not 
4eb0: 61 20 70 75 62 6c 69 73 68 65 64 20 41 50 49 20  a published API 
4ec0: 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75  of SQLite, is su
4ed0: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
4ee0: 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63  without.** notic
4ef0: 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  e, and should no
4f00: 74 20 62 65 20 72 65 66 65 72 65 6e 63 65 64 20  t be referenced 
4f10: 62 79 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74  by programs that
4f20: 20 75 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a   use SQLite..**.
4f30: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64  ** Some of the d
4f40: 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20  efinitions that 
4f50: 61 72 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65  are in this file
4f60: 20 61 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a   are marked as.*
4f70: 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22  * "experimental"
4f80: 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20  .  Experimental 
4f90: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
4fa0: 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66  ormally new.** f
4fb0: 65 61 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79  eatures recently
4fc0: 20 61 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65   added to SQLite
4fd0: 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74  .  We do not ant
4fe0: 69 63 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a  icipate changes.
4ff0: 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74  ** to experiment
5000: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 62 75  al interfaces bu
5010: 74 20 72 65 73 65 72 76 65 20 74 68 65 20 72 69  t reserve the ri
5020: 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  ght to make mino
5030: 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20  r changes.** if 
5040: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
5050: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
5060: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
5070: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
5080: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
5090: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
50a0: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
50b0: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
50c0: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
50d0: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
50e0: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
50f0: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
5100: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
5110: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
5120: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
5130: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
5140: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
5150: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
5160: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
5170: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
5180: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
5190: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
51a0: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
51b0: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
51c0: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
51d0: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
51e0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
51f0: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
5200: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
5210: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
5220: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
5230: 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  cess..*/.#ifndef
5240: 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65   _SQLITE3_H_.#de
5250: 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f  fine _SQLITE3_H_
5260: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
5270: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
5280: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
5290: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
52a0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
52b0: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
52c0: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
52d0: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65   C++..*/.#if 0.e
52e0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
52f0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  if.../*.** Add t
5300: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
5310: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a  erride 'extern'.
5320: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
5330: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
5340: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
5350: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23  extern.#endif..#
5360: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50  ifndef SQLITE_AP
5370: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
5380: 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f  E_API.#endif.../
5390: 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70  *.** These no-op
53a0: 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64   macros are used
53b0: 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74   in front of int
53c0: 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20  erfaces to mark 
53d0: 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  those.** interfa
53e0: 63 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65  ces as either de
53f0: 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65  precated or expe
5400: 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61  rimental.  New a
5410: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
5420: 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65  hould not use de
5430: 70 72 65 63 61 74 65 64 20 69 6e 74 65 72 66 61  precated interfa
5440: 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 73  ces - they are s
5450: 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77  upport for backw
5460: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
5470: 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70  ility only.  App
5480: 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73  lication writers
5490: 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65   should be aware
54a0: 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d   that.** experim
54b0: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
54c0: 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20   are subject to 
54d0: 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20  change in point 
54e0: 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
54f0: 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65  These macros use
5500: 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20  d to resolve to 
5510: 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66  various kinds of
5520: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
5530: 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65  that.** would ge
5540: 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d  nerate warning m
5550: 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65  essages when the
5560: 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75  y were used.  Bu
5570: 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c  t that.** compil
5580: 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75  er magic ended u
5590: 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63  p generating suc
55a0: 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75  h a flurry of bu
55b0: 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61  g reports.** tha
55c0: 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20  t we have taken 
55d0: 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67  it all out and g
55e0: 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e  one back to usin
55f0: 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70  g simple.** noop
5600: 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66   macros..*/.#def
5610: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45  ine SQLITE_DEPRE
5620: 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51  CATED.#define SQ
5630: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
5640: 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20  L../*.** Ensure 
5650: 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65  these symbols we
5660: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
5670: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
5680: 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a  header file..*/.
5690: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
56a0: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51  RSION.# undef SQ
56b0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e  LITE_VERSION.#en
56c0: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54  dif.#ifdef SQLIT
56d0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
56e0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
56f0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
5700: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
5710: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
5720: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
5730: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a  ion Numbers.**.*
5740: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f  * ^(The [SQLITE_
5750: 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72  VERSION] C prepr
5760: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e  ocessor macro in
5770: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68   the sqlite3.h h
5780: 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74  eader.** evaluat
5790: 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c  es to a string l
57a0: 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74  iteral that is t
57b0: 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  he SQLite versio
57c0: 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  n in the.** form
57d0: 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65  at "X.Y.Z" where
57e0: 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20   X is the major 
57f0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
5800: 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20  always 3 for.** 
5810: 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69  SQLite3) and Y i
5820: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73  s the minor vers
5830: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a  ion number and Z
5840: 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20   is the release 
5850: 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54  number.)^.** ^(T
5860: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
5870: 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65  ON_NUMBER] C pre
5880: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
5890: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69  resolves to an i
58a0: 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74  nteger.** with t
58b0: 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30  he value (X*1000
58c0: 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a  000 + Y*1000 + Z
58d0: 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e  ) where X, Y, an
58e0: 64 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65  d Z are the same
58f0: 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64  .** numbers used
5900: 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   in [SQLITE_VERS
5910: 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53  ION].)^.** The S
5920: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
5930: 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76  MBER for any giv
5940: 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  en release of SQ
5950: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a  Lite will also.*
5960: 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  * be larger than
5970: 20 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f   the release fro
5980: 6d 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65  m which it is de
5990: 72 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59  rived.  Either Y
59a0: 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64   will.** be held
59b0: 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20   constant and Z 
59c0: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e  will be incremen
59d0: 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69  ted or else Y wi
59e0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
59f0: 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20  d.** and Z will 
5a00: 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f  be reset to zero
5a10: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65  ..**.** Since ve
5a20: 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51  rsion 3.6.18, SQ
5a30: 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65  Lite source code
5a40: 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64   has been stored
5a50: 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72   in the.** <a hr
5a60: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66  ef="http://www.f
5a70: 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e  ossil-scm.org/">
5a80: 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61  Fossil configura
5a90: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a  tion management.
5aa0: 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20  ** system</a>.  
5ab0: 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  ^The SQLITE_SOUR
5ac0: 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c  CE_ID macro eval
5ad0: 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74  uates to.** a st
5ae0: 72 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74  ring which ident
5af0: 69 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c  ifies a particul
5b00: 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53  ar check-in of S
5b10: 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20  QLite.** within 
5b20: 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  its configuratio
5b30: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73  n management sys
5b40: 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  tem.  ^The SQLIT
5b50: 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73  E_SOURCE_ID.** s
5b60: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74  tring contains t
5b70: 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  he date and time
5b80: 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e   of the check-in
5b90: 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48   (UTC) and an SH
5ba0: 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68  A1.** hash of th
5bb0: 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20  e entire source 
5bc0: 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tree..**.** See 
5bd0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c  also: [sqlite3_l
5be0: 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a  ibversion()],.**
5bf0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
5c00: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20  sion_number()], 
5c10: 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  [sqlite3_sourcei
5c20: 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
5c30: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
5c40: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
5c50: 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  d()]..*/.#define
5c60: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20   SQLITE_VERSION 
5c70: 20 20 20 20 20 20 20 22 33 2e 37 2e 31 33 22 0a         "3.7.13".
5c80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
5c90: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30  ERSION_NUMBER 30
5ca0: 30 37 30 31 33 0a 23 64 65 66 69 6e 65 20 53 51  07013.#define SQ
5cb0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
5cc0: 20 20 20 20 22 32 30 31 32 2d 30 36 2d 30 32 20      "2012-06-02 
5cd0: 31 37 3a 30 39 3a 34 36 20 63 34 62 38 36 32 31  17:09:46 c4b8621
5ce0: 31 32 35 63 65 37 37 33 30 38 62 30 36 36 39 32  125ce77308b06692
5cf0: 64 39 32 66 37 30 35 38 36 62 31 30 30 35 35 61  d92f70586b10055a
5d00: 39 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  9"../*.** CAPI3R
5d10: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
5d20: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
5d30: 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  bers.** KEYWORDS
5d40: 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  : sqlite3_versio
5d50: 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  n, sqlite3_sourc
5d60: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
5d70: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
5d80: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
5d90: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
5da0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
5db0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
5dc0: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
5dd0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
5de0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
5df0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
5e00: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
5e10: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
5e20: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
5e30: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
5e40: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
5e50: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
5e60: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
5e70: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
5e80: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
5e90: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
5ea0: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
5eb0: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
5ec0: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
5ed0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
5ee0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
5ef0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
5f00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
5f10: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
5f20: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
5f30: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
5f40: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
5f50: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
5f60: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
5f70: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
5f80: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
5f90: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
5fa0: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
5fb0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
5fc0: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
5fd0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
5fe0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
5ff0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
6000: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
6010: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
6020: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
6030: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
6040: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
6050: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
6060: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
6070: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
6080: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
6090: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
60a0: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
60b0: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
60c0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
60d0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
60e0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
60f0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
6100: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
6110: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
6120: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
6130: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
6140: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
6150: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
6160: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
6170: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
6180: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
6190: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
61a0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
61b0: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
61c0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
61d0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
61e0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
61f0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
6200: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
6210: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
6220: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
6230: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
6240: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
6250: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
6260: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
6270: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
6280: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
6290: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
62a0: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
62b0: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
62c0: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
62d0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
62e0: 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76  t char sqlite3_v
62f0: 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54  ersion[] = SQLIT
6300: 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54  E_VERSION;.SQLIT
6310: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
6320: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
6330: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  sion(void);.SQLI
6340: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
6350: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
6360: 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  eid(void);.SQLIT
6370: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
6380: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
6390: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ber(void);../*.*
63a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
63b0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d  Time Library Com
63c0: 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  pilation Options
63d0: 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a   Diagnostics.**.
63e0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
63f0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
6400: 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  ed() function re
6410: 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a  turns 0 or 1 .**
6420: 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74   indicating whet
6430: 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65  her the specifie
6440: 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66  d option was def
6450: 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70  ined at .** comp
6460: 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  ile time.  ^The 
6470: 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d  SQLITE_ prefix m
6480: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72  ay be omitted fr
6490: 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f  om the .** optio
64a0: 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f  n name passed to
64b0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
64c0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20  option_used().  
64d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
64e0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
64f0: 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  n_get() function
6500: 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e   allows iteratin
6510: 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69  g.** over the li
6520: 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68  st of options th
6530: 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20  at were defined 
6540: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20  at compile time 
6550: 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20  by.** returning 
6560: 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65  the N-th compile
6570: 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72   time option str
6580: 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f  ing.  ^If N is o
6590: 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20  ut of range,.** 
65a0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
65b0: 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75  ption_get() retu
65c0: 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
65d0: 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  er.  ^The SQLITE
65e0: 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20  _ .** prefix is 
65f0: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79  omitted from any
6600: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
6610: 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
6620: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6630: 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70  et()..**.** ^Sup
6640: 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61  port for the dia
6650: 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  gnostic function
6660: 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  s sqlite3_compil
6670: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a  eoption_used().*
6680: 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
6690: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
66a0: 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  ) may be omitted
66b0: 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74   by specifying t
66c0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
66d0: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f  MIT_COMPILEOPTIO
66e0: 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20  N_DIAGS] option 
66f0: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
6700: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
6710: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b   SQL functions [
6720: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
6730: 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64  tion_used()] and
6740: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  .** [sqlite_comp
6750: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d  ileoption_get()]
6760: 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c   and the [compil
6770: 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61  e_options pragma
6780: 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  ]..*/.#ifndef SQ
6790: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
67a0: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51  EOPTION_DIAGS.SQ
67b0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
67c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
67d0: 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68  on_used(const ch
67e0: 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53  ar *zOptName);.S
67f0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
6800: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
6810: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
6820: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
6830: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6840: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
6850: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
6860: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
6870: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
6880: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
6890: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
68a0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
68b0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
68c0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
68d0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
68e0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
68f0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
6900: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
6910: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
6920: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
6930: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
6940: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
6950: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
6960: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
6970: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
6980: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
6990: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
69a0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
69b0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
69c0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
69d0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
69e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
69f0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
6a00: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
6a10: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
6a20: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
6a30: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
6a40: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
6a50: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
6a60: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
6a70: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
6a80: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
6a90: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
6aa0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
6ab0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
6ac0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
6ad0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
6ae0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
6af0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
6b00: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
6b10: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
6b20: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
6b30: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
6b40: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
6b50: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
6b60: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
6b70: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
6b80: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
6b90: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
6ba0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
6bb0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
6bc0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
6bd0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
6be0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
6bf0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
6c00: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
6c10: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
6c20: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
6c30: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
6c40: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
6c50: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
6c60: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
6c70: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
6c80: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
6c90: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
6ca0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
6cb0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
6cc0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
6cd0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
6ce0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
6cf0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
6d00: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
6d10: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
6d20: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
6d30: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
6d40: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
6d50: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
6d60: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
6d70: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
6d80: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
6d90: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
6da0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
6db0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
6dc0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
6dd0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
6de0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
6df0: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
6e00: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
6e10: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
6e20: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
6e30: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
6e40: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
6e50: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
6e60: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
6e70: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
6e80: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
6e90: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
6ea0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
6eb0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
6ec0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
6ed0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
6ee0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
6ef0: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
6f00: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
6f10: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
6f20: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
6f30: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
6f40: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
6f50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
6f60: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
6f70: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
6f80: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
6f90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
6fa0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
6fb0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
6fc0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
6fd0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
6fe0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
6ff0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
7000: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
7010: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
7020: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
7030: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
7040: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
7050: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
7060: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
7070: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
7080: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
7090: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
70a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
70b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
70c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
70d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
70e0: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
70f0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
7100: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
7110: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
7120: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
7130: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
7140: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
7150: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
7160: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
7170: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
7180: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
7190: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
71a0: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
71b0: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
71c0: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
71d0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
71e0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
71f0: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
7200: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
7210: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
7220: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
7230: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
7240: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
7250: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
7260: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
7270: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
7280: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
7290: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
72a0: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
72b0: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
72c0: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
72d0: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
72e0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
72f0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
7300: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
7310: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
7320: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
7330: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
7340: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
7350: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
7360: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
7370: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
7380: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
7390: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
73a0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
73b0: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
73c0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
73d0: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
73e0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
73f0: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
7400: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
7410: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
7420: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
7430: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
7440: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
7450: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
7460: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
7470: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
7480: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
7490: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
74a0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
74b0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
74c0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
74d0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
74e0: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49  ef unsigned SQLI
74f0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
7500: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
7510: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
7520: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
7530: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
7540: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
7550: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
7560: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
7570: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
7580: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
7590: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
75a0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
75b0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
75c0: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
75d0: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
75e0: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64  64;.#endif.typed
75f0: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  ef sqlite_int64 
7600: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74  sqlite3_int64;.t
7610: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69  ypedef sqlite_ui
7620: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e  nt64 sqlite3_uin
7630: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63  t64;../*.** If c
7640: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70  ompiling for a p
7650: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61  rocessor that la
7660: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  cks floating poi
7670: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73  nt support,.** s
7680: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65  ubstitute intege
7690: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70  r for floating-p
76a0: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  oint..*/.#ifdef 
76b0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
76c0: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
76d0: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
76e0: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
76f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7700: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
7710: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
7720: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
7730: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71  3_close() and sq
7740: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
7750: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
7760: 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72  structors.** for
7770: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
7780: 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73  bject..** ^Calls
7790: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   to sqlite3_clos
77a0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
77b0: 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72  close_v2() retur
77c0: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 0a 2a  n SQLITE_OK if.*
77d0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  * the [sqlite3] 
77e0: 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73  object is succes
77f0: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64  sfully destroyed
7800: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61   and all associa
7810: 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73  ted.** resources
7820: 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64   are deallocated
7830: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
7840: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7850: 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65  ion is associate
7860: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
7870: 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  ed prepared.** s
7880: 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66  tatements or unf
7890: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
78a0: 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74  backup objects t
78b0: 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  hen sqlite3_clos
78c0: 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76  e().** will leav
78d0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
78e0: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61  onnection open a
78f0: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
7900: 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20  E_BUSY]..** ^If 
7910: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
7920: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
7930: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72  h unfinalized pr
7940: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
7950: 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69 6e 69 73  s.** and unfinis
7960: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  hed sqlite3_back
7970: 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ups, then the da
7980: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7990: 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20  n becomes.** an 
79a0: 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65  unusable "zombie
79b0: 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74  " which will aut
79c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65  omatically be de
79d0: 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74  allocated when t
79e0: 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61  he.** last prepa
79f0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
7a00: 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68   finalized or th
7a10: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62  e last sqlite3_b
7a20: 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69  ackup is.** fini
7a30: 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  shed.  The sqlit
7a40: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e  e3_close_v2() in
7a50: 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e  terface is inten
7a60: 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68  ded for use with
7a70: 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67  .** host languag
7a80: 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62  es that are garb
7a90: 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61  age collected, a
7aa0: 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64  nd where the ord
7ab0: 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64  er in which.** d
7ac0: 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63  estructors are c
7ad0: 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61  alled is arbitra
7ae0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ry..**.** Applic
7af0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73  ations should [s
7b00: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
7b10: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
7b20: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
7b30: 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ents],.** [sqlit
7b40: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20  e3_blob_close | 
7b50: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42  close] all [BLOB
7b60: 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a   handles], and .
7b70: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
7b80: 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69  up_finish | fini
7b90: 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33  sh] all [sqlite3
7ba0: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
7bb0: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
7bc0: 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ith the [sqlite3
7bd0: 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74  ] object prior t
7be0: 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  o attempting to 
7bf0: 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74  close the object
7c00: 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65  .  ^If.** sqlite
7c10: 33 5f 63 6c 6f 73 65 28 29 20 69 73 20 63 61 6c  3_close() is cal
7c20: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
7c30: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
7c40: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
7c50: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
7c60: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
7c70: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
7c80: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
7c90: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
7ca0: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
7cb0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
7cc0: 20 62 75 74 20 74 68 65 20 64 65 61 6c 6c 6f 63   but the dealloc
7cd0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f  ation.** of reso
7ce0: 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65  urces is deferre
7cf0: 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65  d until all [pre
7d00: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
7d10: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
7d20: 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  ],.** and [sqlit
7d30: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
7d40: 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74  ts are also dest
7d50: 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  royed..**.** ^If
7d60: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
7d70: 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65  ject is destroye
7d80: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61  d while a transa
7d90: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a  ction is open,.*
7da0: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  * the transactio
7db0: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  n is automatical
7dc0: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
7dd0: 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61  **.** The C para
7de0: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
7df0: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20  3_close(C)] and 
7e00: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
7e10: 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  2(C)].** must be
7e20: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a   either a NULL.*
7e30: 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20  * pointer or an 
7e40: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
7e50: 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65   pointer obtaine
7e60: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
7e70: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
7e80: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
7e90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
7ea0: 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e  pen_v2()], and n
7eb0: 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c  ot previously cl
7ec0: 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  osed..** ^Callin
7ed0: 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  g sqlite3_close(
7ee0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ) or sqlite3_clo
7ef0: 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e  se_v2() with a N
7f00: 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61  ULL pointer.** a
7f10: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72  rgument is a har
7f20: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
7f30: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
7f40: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c  qlite3_close(sql
7f50: 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
7f60: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
7f70: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
7f80: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
7f90: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
7fa0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
7fb0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
7fc0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
7fd0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
7fe0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
7ff0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
8000: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
8010: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
8020: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
8030: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
8040: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
8050: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
8060: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
8070: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
8080: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
8090: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
80a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
80b0: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
80c0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
80d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
80e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
80f0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
8100: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
8110: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
8120: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
8130: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
8140: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
8150: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
8160: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
8170: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
8180: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
8190: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
81a0: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
81b0: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
81c0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
81d0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
81e0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
81f0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
8200: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
8210: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
8220: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8230: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
8240: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
8250: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
8260: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
8270: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
8280: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
8290: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
82a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
82b0: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
82c0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
82d0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
82e0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
82f0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
8300: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
8310: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
8320: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
8330: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
8340: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
8350: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
8360: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
8370: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
8380: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
8390: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
83a0: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
83b0: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
83c0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
83d0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
83e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
83f0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
8400: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
8410: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
8420: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
8430: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
8440: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
8450: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
8460: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
8470: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
8480: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
8490: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
84a0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
84b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
84c0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
84d0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
84e0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
84f0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
8500: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
8510: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
8520: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
8530: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
8540: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
8550: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
8560: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
8570: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
8580: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
8590: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
85a0: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
85b0: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
85c0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
85d0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
85e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
85f0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
8600: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
8610: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
8620: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
8630: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
8640: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
8650: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
8660: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
8670: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
8680: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
8690: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
86a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
86b0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
86c0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
86d0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
86e0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
86f0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
8700: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
8710: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
8720: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
8730: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
8740: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
8750: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
8760: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
8770: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
8780: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
8790: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
87a0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
87b0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
87c0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
87d0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
87e0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
87f0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
8800: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
8810: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
8820: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
8830: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
8840: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
8850: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
8860: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
8870: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
8880: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
8890: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
88a0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
88b0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
88c0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
88d0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
88e0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
88f0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
8900: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
8910: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
8920: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
8930: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
8940: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
8950: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
8960: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
8970: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
8980: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
8990: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
89a0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
89b0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
89c0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
89d0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
89e0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
89f0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
8a00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
8a10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
8a20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
8a30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
8a40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
8a50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
8a60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
8a70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
8a80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
8a90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
8aa0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
8ab0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
8ac0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
8ad0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
8ae0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
8af0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
8b00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
8b10: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
8b20: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
8b30: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
8b40: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
8b50: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
8b60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8b70: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
8b80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
8b90: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74  t not close [dat
8ba0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8bb0: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
8bc0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
8bd0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
8be0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
8bf0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8c00: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
8c10: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
8c20: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
8c30: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
8c40: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
8c50: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
8c60: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
8c70: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
8c80: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
8c90: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
8ca0: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
8cb0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
8cc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
8cd0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
8ce0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8cf0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
8d00: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
8d10: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
8d20: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
8d30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
8d40: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
8d50: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
8d60: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
8d70: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
8d80: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
8d90: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
8da0: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
8db0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8dc0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
8dd0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
8de0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
8df0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
8e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8e10: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
8e20: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
8e30: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
8e40: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
8e50: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
8e60: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
8e70: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
8e80: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
8e90: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
8ea0: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
8eb0: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
8ec0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
8ed0: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
8ee0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
8ef0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
8f00: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
8f10: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
8f20: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
8f30: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
8f40: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
8f50: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
8f60: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
8f70: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
8f80: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
8f90: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
8fa0: 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b  ult codes],.** [
8fb0: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
8fc0: 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51 4c  conflict()] [SQL
8fd0: 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
8fe0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f  esult codes]..*/
8ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9000: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
9010: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
9020: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
9030: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
9040: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
9050: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
9060: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
9070: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
9080: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
9090: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
90a0: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
90b0: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
90c0: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
90d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
90e0: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
90f0: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
9100: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
9110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
9120: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
9130: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
9140: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
9150: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
9160: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
9170: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
9180: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
9190: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
91a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
91b0: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
91c0: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
91d0: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
91e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
91f0: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
9200: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
9210: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
9220: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
9230: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
9240: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
9250: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
9260: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
9270: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
9280: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
9290: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
92a0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
92b0: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
92c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
92d0: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
92e0: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
92f0: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
9300: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9310: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
9320: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
9330: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
9340: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
9350: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
9360: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
9370: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
9380: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
9390: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
93a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
93b0: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
93c0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
93d0: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
93e0: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
93f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
9400: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
9410: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
9420: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9430: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
9440: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
9450: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
9460: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
9470: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
9480: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
9490: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61    16   /* Databa
94a0: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23  se is empty */.#
94b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
94c0: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
94d0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
94e0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
94f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9500: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
9510: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
9520: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
9530: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
9540: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
9550: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
9560: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
9570: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
9580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9590: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
95a0: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
95b0: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
95c0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
95d0: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
95e0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
95f0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
9600: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
9610: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
9620: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
9630: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
9640: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
9650: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
9660: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
9670: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
9680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9690: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
96a0: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
96b0: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
96c0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
96d0: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
96e0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
96f0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
9700: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
9710: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
9720: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
9730: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
9740: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
9750: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
9760: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
9770: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
9780: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
9790: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
97a0: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
97b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
97c0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
97d0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
97e0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
97f0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
9800: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
9810: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
9820: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
9830: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
9840: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
9850: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
9860: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
9870: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
9880: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
9890: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
98a0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
98b0: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
98c0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
98d0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
98e0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
98f0: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
9900: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
9910: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
9920: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
9930: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
9940: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
9950: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
9960: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
9970: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
9980: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
9990: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
99a0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
99b0: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
99c0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
99d0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
99e0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
99f0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
9a00: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
9a10: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
9a20: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
9a30: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
9a40: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
9a50: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
9a60: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
9a70: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
9a80: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
9a90: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
9aa0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
9ab0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
9ac0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
9ad0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9ae0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
9af0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
9b00: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
9b10: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
9b20: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
9b30: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
9b40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
9b50: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
9b60: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
9b70: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
9b80: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
9b90: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
9ba0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
9bb0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
9bc0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
9bd0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
9be0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
9bf0: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
9c00: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
9c10: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
9c20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
9c30: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
9c40: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
9c50: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
9c60: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
9c70: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
9c80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9c90: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
9ca0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9cb0: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
9cc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
9cd0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
9ce0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
9cf0: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
9d00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9d10: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
9d20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9d30: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
9d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9d50: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
9d60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9d70: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
9d80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
9d90: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
9da0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
9db0: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
9dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
9dd0: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
9de0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
9df0: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
9e00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
9e10: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
9e20: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
9e30: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
9e40: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
9e50: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
9e60: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
9e70: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
9e80: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
9e90: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
9ea0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9eb0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
9ec0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
9ed0: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
9ee0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9ef0: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
9f00: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
9f10: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
9f20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9f30: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
9f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
9f50: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
9f60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9f70: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
9f80: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
9f90: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
9fa0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9fb0: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
9fc0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
9fd0: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
9fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9ff0: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
a000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
a010: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
a020: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a030: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
a040: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
a050: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
a060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a070: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
a080: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
a090: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
a0a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a0b0: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
a0c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a0d0: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
a0e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a0f0: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
a100: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a110: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
a120: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a130: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
a140: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a150: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
a160: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a170: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
a180: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a190: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
a1a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a1b0: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
a1c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
a1d0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
a1e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a1f0: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
a200: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
a210: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
a220: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
a230: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
a240: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
a250: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
a260: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
a270: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
a280: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
a290: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
a2a0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
a2b0: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
a2c0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
a2d0: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
a2e0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
a2f0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
a300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
a310: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
a320: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
a330: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
a340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
a350: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
a360: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
a370: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
a380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a390: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
a3a0: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
a3b0: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
a3c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a3d0: 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b  E_ABORT_ROLLBACK
a3e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
a3f0: 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29  E_ABORT | (2<<8)
a400: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
a410: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
a420: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
a430: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
a440: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
a450: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
a460: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
a470: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
a480: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
a490: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
a4a0: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
a4b0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
a4c0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
a4d0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
a4e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a4f0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
a500: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
a510: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a520: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a540: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
a550: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
a560: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a570: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a580: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a590: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
a5a0: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
a5b0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a5c0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a5d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a5e0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
a5f0: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
a600: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a620: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
a630: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
a640: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a650: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a660: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
a670: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
a680: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a690: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a6a0: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
a6b0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
a6c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a6d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a6e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a6f0: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
a700: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
a710: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a720: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a740: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
a750: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
a760: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a780: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
a790: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
a7a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a7b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a7c0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
a7d0: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
a7e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a7f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a800: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
a810: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
a820: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a840: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
a850: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
a860: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a880: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
a890: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
a8a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a8b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a8c0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
a8d0: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
a8e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a8f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a900: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
a910: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
a920: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a930: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a950: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
a960: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
a970: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a980: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a990: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a9a0: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
a9b0: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
a9c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a9d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a9e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a9f0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
aa00: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
aa10: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
aa20: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
aa30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
aa40: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
aa50: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
aa60: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
aa70: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
aa80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
aa90: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
aaa0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
aab0: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
aac0: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
aad0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
aae0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
aaf0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
ab00: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
ab10: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
ab20: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
ab30: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
ab40: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
ab50: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
ab60: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
ab70: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
ab80: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
ab90: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
aba0: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
abb0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
abc0: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
abd0: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
abe0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
abf0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
ac00: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
ac10: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
ac20: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
ac30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
ac40: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
ac50: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
ac60: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
ac70: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
ac80: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
ac90: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
aca0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
acb0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
acc0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
acd0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
ace0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
acf0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
ad00: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
ad10: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
ad20: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
ad30: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
ad40: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
ad50: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
ad60: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
ad70: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
ad80: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
ad90: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
ada0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
adb0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
adc0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
add0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
ade0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
adf0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
ae00: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
ae10: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
ae20: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
ae30: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
ae40: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
ae50: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
ae60: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
ae70: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
ae80: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
ae90: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
aea0: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
aeb0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
aec0: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
aed0: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
aee0: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
aef0: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
af00: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
af10: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
af20: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
af30: 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e  anged..*/.#defin
af40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
af50: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
af60: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
af70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
af80: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
af90: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
afa0: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
afb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
afc0: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
afd0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
afe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
aff0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
b000: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
b010: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
b020: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
b030: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
b040: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
b050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
b060: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
b070: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
b080: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
b090: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
b0a0: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
b0b0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
b0c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
b0d0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
b0e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
b0f0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b100: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
b110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
b120: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
b130: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
b140: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
b150: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
b160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
b170: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
b180: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
b190: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
b1a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
b1b0: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
b1c0: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64  N  0x00000800.#d
b1d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
b1e0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
b1f0: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30  RWRITE    0x0000
b200: 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  1000../*.** CAPI
b210: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
b220: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
b230: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
b240: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
b250: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
b260: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
b270: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
b280: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
b290: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
b2a0: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
b2b0: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
b2c0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
b2d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
b2e0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
b2f0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
b300: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
b310: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
b320: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
b330: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
b340: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
b350: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
b360: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
b370: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
b380: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
b390: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
b3a0: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
b3b0: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
b3c0: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
b3d0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
b3e0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
b3f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
b400: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
b410: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
b420: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
b430: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
b440: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
b450: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
b460: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
b470: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
b480: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
b490: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
b4a0: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
b4b0: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
b4c0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
b4d0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
b4e0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
b4f0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
b500: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
b510: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
b520: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
b530: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
b540: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
b550: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
b560: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
b570: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
b580: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
b590: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
b5a0: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
b5b0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
b5c0: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
b5d0: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
b5e0: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
b5f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
b600: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
b610: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
b620: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
b630: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
b640: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
b650: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
b660: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
b670: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
b680: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
b690: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
b6a0: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
b6b0: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
b6c0: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
b6d0: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
b6e0: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
b6f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
b700: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
b710: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
b720: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
b730: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
b740: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
b750: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
b760: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
b770: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
b780: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
b790: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
b7a0: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
b7b0: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
b7c0: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
b7d0: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
b7e0: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
b7f0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
b800: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
b810: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
b820: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
b830: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
b840: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
b850: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
b860: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
b870: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
b880: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
b890: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
b8a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
b8b0: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
b8c0: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
b8d0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
b8e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
b8f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b900: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
b910: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
b920: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
b930: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
b940: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
b950: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
b960: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
b970: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
b980: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
b990: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
b9a0: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
b9b0: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
b9c0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
b9d0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
b9e0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
b9f0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
ba00: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
ba10: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
ba20: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
ba30: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
ba40: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
ba50: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
ba60: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
ba70: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
ba80: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
ba90: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
baa0: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
bab0: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
bac0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
bad0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
bae0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
baf0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
bb00: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
bb10: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
bb20: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
bb30: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
bb40: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
bb50: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
bb60: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
bb70: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
bb80: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
bb90: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
bba0: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
bbb0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
bbc0: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
bbd0: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
bbe0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
bbf0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
bc00: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
bc10: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
bc20: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
bc30: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
bc40: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
bc50: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
bc60: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
bc70: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
bc80: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
bc90: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
bca0: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
bcb0: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
bcc0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
bcd0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
bce0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
bcf0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
bd00: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
bd10: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
bd20: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
bd30: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
bd40: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
bd50: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
bd60: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
bd70: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
bd80: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
bd90: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
bda0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
bdb0: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
bdc0: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
bdd0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
bde0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
bdf0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
be00: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
be10: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
be20: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
be30: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
be40: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
be50: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
be60: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
be70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
be80: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
be90: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
bea0: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
beb0: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
bec0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
bed0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
bee0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
bef0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
bf00: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
bf10: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
bf20: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
bf30: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
bf40: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
bf50: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
bf60: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
bf70: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
bf80: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
bf90: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
bfa0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
bfb0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
bfc0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
bfd0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
bfe0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
bff0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
c000: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
c010: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
c020: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
c030: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
c040: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
c050: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
c060: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
c070: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
c080: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
c090: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
c0a0: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
c0b0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
c0c0: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
c0d0: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
c0e0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
c0f0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
c100: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
c110: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
c120: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
c130: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
c140: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
c150: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
c160: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
c170: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
c180: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
c190: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
c1a0: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
c1b0: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
c1c0: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
c1d0: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
c1e0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
c1f0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
c200: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
c210: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
c220: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
c230: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
c240: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
c250: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
c260: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
c270: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
c280: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
c290: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
c2a0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
c2b0: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
c2c0: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
c2d0: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
c2e0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
c2f0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
c300: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
c310: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
c320: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
c330: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
c340: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
c350: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
c360: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
c370: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
c380: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
c390: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
c3a0: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
c3b0: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
c3c0: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
c3d0: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
c3e0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
c3f0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
c400: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
c410: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
c420: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
c430: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
c440: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
c450: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
c460: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
c470: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
c480: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
c490: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
c4a0: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
c4b0: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
c4c0: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
c4d0: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
c4e0: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
c4f0: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
c500: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
c510: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
c520: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
c530: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
c540: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
c550: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
c560: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
c570: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
c580: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
c590: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
c5a0: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
c5b0: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
c5c0: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
c5d0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
c5e0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
c5f0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
c600: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
c610: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
c620: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
c630: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
c640: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
c650: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
c660: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
c670: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
c680: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
c690: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
c6a0: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
c6b0: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
c6c0: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
c6d0: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
c6e0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
c6f0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
c700: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
c710: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
c720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c730: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
c740: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
c750: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
c760: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
c770: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
c780: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
c790: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
c7a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
c7b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
c7c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
c7d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
c7e0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
c7f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
c800: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
c810: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
c820: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
c830: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
c840: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
c850: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
c860: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
c870: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
c880: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
c890: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
c8a0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
c8b0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
c8c0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
c8d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
c8e0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
c8f0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
c900: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
c910: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
c920: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
c930: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
c940: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
c950: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
c960: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
c970: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
c980: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
c990: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
c9a0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
c9b0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
c9c0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
c9d0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
c9e0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
c9f0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
ca00: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
ca10: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
ca20: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
ca30: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
ca40: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
ca50: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
ca60: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
ca70: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
ca80: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
ca90: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
caa0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
cab0: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
cac0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
cad0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
cae0: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
caf0: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
cb00: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
cb10: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
cb20: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
cb30: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
cb40: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
cb50: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
cb60: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
cb70: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
cb80: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
cb90: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
cba0: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
cbb0: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
cbc0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
cbd0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
cbe0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
cbf0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
cc00: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
cc10: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
cc20: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
cc30: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
cc40: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
cc50: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
cc60: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
cc70: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
cc80: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
cc90: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
cca0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
ccb0: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
ccc0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
ccd0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
cce0: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
ccf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
cd00: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
cd10: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
cd20: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
cd30: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
cd40: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
cd50: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
cd60: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
cd70: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
cd80: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
cd90: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
cda0: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
cdb0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
cdc0: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
cdd0: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
cde0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
cdf0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
ce00: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
ce10: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
ce20: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
ce30: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
ce40: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
ce50: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
ce60: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
ce70: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
ce80: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
ce90: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
cea0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
ceb0: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
cec0: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
ced0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
cee0: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
cef0: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
cf00: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
cf10: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
cf20: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
cf30: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
cf40: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
cf50: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
cf60: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
cf70: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
cf80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
cf90: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
cfa0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
cfb0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
cfc0: 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 2 */.  /* Ad
cfd0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
cfe0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
cff0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
d000: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
d010: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
d020: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
d030: 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  codes.**.** Thes
d040: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
d050: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
d060: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
d070: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
d080: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
d090: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
d0a0: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
d0b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
d0c0: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
d0d0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
d0e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
d0f0: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
d100: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
d110: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
d120: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
d130: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
d140: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
d150: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
d160: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
d170: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
d180: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
d190: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
d1a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
d1b0: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
d1c0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
d1d0: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
d1e0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
d1f0: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
d200: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
d210: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
d220: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
d230: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
d240: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
d250: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
d260: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
d270: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
d280: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20   is defined..** 
d290: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  <ul>.** <li>[[SQ
d2a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
d2b0: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
d2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
d2d0: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
d2e0: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
d2f0: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
d300: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
d310: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
d320: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
d330: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
d340: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
d350: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
d360: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
d370: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
d380: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
d390: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
d3a0: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
d3b0: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
d3c0: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
d3d0: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
d3e0: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
d3f0: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
d400: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
d410: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
d420: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
d430: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
d440: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
d450: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
d460: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
d470: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
d480: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
d490: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
d4a0: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
d4b0: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
d4c0: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
d4d0: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
d4e0: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
d4f0: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
d500: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
d510: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
d520: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
d530: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
d540: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
d550: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
d560: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
d570: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
d580: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
d590: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
d5a0: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
d5b0: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
d5c0: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
d5d0: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
d5e0: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
d5f0: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
d600: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
d610: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
d620: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
d630: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
d640: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d650: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
d660: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
d670: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
d680: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
d690: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
d6a0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
d6b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
d6c0: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
d6d0: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
d6e0: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
d6f0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
d700: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
d710: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
d720: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
d730: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
d740: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
d750: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
d760: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
d770: 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ED]].** ^(The [S
d780: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
d790: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
d7a0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
d7b0: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
d7c0: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
d7d0: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
d7e0: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
d7f0: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
d800: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
d810: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d820: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
d830: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
d840: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
d850: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
d860: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
d870: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
d880: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
d890: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
d8a0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
d8b0: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
d8c0: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
d8d0: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
d8e0: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
d8f0: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
d900: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
d910: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
d920: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
d930: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
d940: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
d950: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
d960: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
d970: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
d980: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
d990: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
d9a0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
d9b0: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
d9c0: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
d9d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
d9e0: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
d9f0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
da00: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
da10: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20  V_RETRY] opcode 
da20: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
da30: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a  gure automatic.*
da40: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61  * retry counts a
da50: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72  nd intervals for
da60: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f   certain disk I/
da70: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72  O operations for
da80: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   the.** windows 
da90: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  [VFS] in order t
daa0: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
dab0: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73  ness in the pres
dac0: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d  ence of.** anti-
dad0: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20  virus programs. 
dae0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
daf0: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c   windows VFS wil
db00: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61  l retry file rea
db10: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65  d,.** file write
db20: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74  , and file delet
db30: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  e operations up 
db40: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
db50: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
db60: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
db70: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
db80: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
db90: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
dba0: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
dbb0: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
dbc0: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
dbd0: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
dbe0: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
dbf0: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73  code allows thes
dc00: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30  e two values (10
dc10: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
dc20: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
dc30: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
dc40: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
dc50: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
dc60: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
dc70: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
dc80: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
dc90: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
dca0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
dcb0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
dcc0: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
dcd0: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
dce0: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74  irst integer i t
dcf0: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
dd00: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
dd10: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
dd20: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
dd30: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
dd40: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
dd50: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
dd60: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
dd70: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
dd80: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
dd90: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
dda0: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
ddb0: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
ddc0: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
ddd0: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
dde0: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
ddf0: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
de00: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
de10: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
de20: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
de30: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
de40: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
de50: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
de60: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
de70: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
de80: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
de90: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
dea0: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
deb0: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
dec0: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
ded0: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
dee0: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
def0: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
df00: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
df10: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
df20: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
df30: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
df40: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
df50: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
df60: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
df70: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
df80: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
df90: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
dfa0: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
dfb0: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
dfc0: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
dfd0: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
dfe0: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
dff0: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
e000: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
e010: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
e020: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
e030: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
e040: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
e050: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
e060: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
e070: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
e080: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
e090: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
e0a0: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
e0b0: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
e0c0: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
e0d0: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
e0e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
e0f0: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
e100: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
e110: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
e120: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
e130: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
e140: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
e150: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
e160: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
e170: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
e180: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
e190: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
e1a0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
e1b0: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
e1c0: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
e1d0: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
e1e0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
e1f0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
e200: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
e210: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
e220: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
e230: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
e240: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
e250: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
e260: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
e270: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
e280: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
e290: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
e2a0: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
e2b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
e2c0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
e2d0: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
e2e0: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
e2f0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
e300: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
e310: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
e320: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
e330: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
e340: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
e350: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
e360: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
e370: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
e380: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
e390: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
e3a0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
e3b0: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
e3c0: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
e3d0: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
e3e0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
e3f0: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
e400: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
e410: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
e420: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
e430: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
e440: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
e450: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
e460: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
e470: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
e480: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
e490: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
e4a0: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
e4b0: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
e4c0: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
e4d0: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
e4e0: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
e4f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
e500: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
e510: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
e520: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
e530: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
e540: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
e550: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
e560: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
e570: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
e580: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
e590: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
e5a0: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
e5b0: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
e5c0: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
e5d0: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
e5e0: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
e5f0: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
e600: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
e610: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
e620: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
e630: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
e640: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
e650: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
e660: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
e670: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
e680: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
e690: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
e6a0: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
e6b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
e6c0: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
e6d0: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
e6e0: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
e6f0: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
e700: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
e710: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
e720: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
e730: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
e740: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
e750: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
e760: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
e770: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
e780: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
e790: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
e7a0: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
e7b0: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
e7c0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
e7d0: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
e7e0: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
e7f0: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
e800: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
e810: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
e820: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
e830: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
e840: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
e850: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
e860: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
e870: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
e880: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
e890: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
e8a0: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
e8b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
e8c0: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
e8d0: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
e8e0: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
e8f0: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
e900: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
e910: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
e920: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
e930: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
e940: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
e950: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
e960: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
e970: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
e980: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
e990: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
e9a0: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
e9b0: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
e9c0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
e9d0: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
e9e0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
e9f0: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
ea00: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
ea10: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
ea20: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
ea30: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
ea40: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ea50: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
ea60: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
ea70: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
ea80: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
ea90: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
eaa0: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
eab0: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
eac0: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
ead0: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
eae0: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
eaf0: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
eb00: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
eb10: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
eb20: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
eb30: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
eb40: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
eb50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
eb60: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
eb70: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
eb80: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
eb90: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
eba0: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
ebb0: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
ebc0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
ebd0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
ebe0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
ebf0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
ec00: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
ec10: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
ec20: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
ec30: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
ec40: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
ec50: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
ec60: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
ec70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  red statement.  
ec80: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
ec90: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
eca0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
ecb0: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
ecc0: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
ecd0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
ece0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
ecf0: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
ed00: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
ed10: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
ed20: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
ed30: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
ed40: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
ed50: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
ed60: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
ed70: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
ed80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ed90: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
eda0: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
edb0: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
edc0: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
edd0: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
ede0: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
edf0: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
ee00: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
ee10: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f 75 6c  tements..** </ul
ee20: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
ee30: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
ee40: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
ee50: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
ee60: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
ee70: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
ee80: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
ee90: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
eea0: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
eeb0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
eec0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
eed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34                 4
eee0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
eef0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
ef00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
ef10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ef20: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
ef30: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
ef40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ef50: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
ef60: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
ef70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ef80: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
ef90: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
efa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
efb0: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
efc0: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
efd0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
efe0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
eff0: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
f000: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
f010: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
f020: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
f030: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
f040: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
f050: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
f060: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
f070: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
f080: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
f090: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
f0a0: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
f0b0: 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41      14../*.** CA
f0c0: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
f0d0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
f0e0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
f0f0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
f100: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
f110: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
f120: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
f130: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
f140: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
f150: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
f160: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
f170: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
f180: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
f190: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
f1a0: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
f1b0: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
f1c0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
f1d0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
f1e0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
f1f0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
f200: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
f210: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
f220: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
f230: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
f240: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
f250: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
f260: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
f270: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
f280: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
f290: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
f2a0: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
f2b0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
f2c0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
f2d0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
f2e0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
f2f0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
f300: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
f310: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
f320: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
f330: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
f340: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
f350: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
f360: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
f370: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
f380: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
f390: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
f3a0: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
f3b0: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
f3c0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
f3d0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
f3e0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
f3f0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
f400: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
f410: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
f420: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
f430: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
f440: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
f450: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
f460: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
f470: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
f480: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
f490: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
f4a0: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
f4b0: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
f4c0: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
f4d0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
f4e0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
f4f0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
f500: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
f510: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
f520: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
f530: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
f540: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
f550: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
f560: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
f570: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
f580: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
f590: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
f5a0: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
f5b0: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
f5c0: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
f5d0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
f5e0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
f5f0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
f600: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
f610: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
f620: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
f630: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
f640: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
f650: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
f660: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
f670: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
f680: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
f690: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
f6a0: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
f6b0: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
f6c0: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
f6d0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
f6e0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
f6f0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
f700: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
f710: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
f720: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
f730: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
f740: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
f750: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
f760: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
f770: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
f780: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
f790: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
f7a0: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
f7b0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
f7c0: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
f7d0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
f7e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
f7f0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
f800: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
f810: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
f820: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
f830: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
f840: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
f850: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
f860: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
f870: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
f880: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
f890: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
f8a0: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
f8b0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
f8c0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
f8d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
f8e0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
f8f0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
f900: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
f910: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
f920: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
f930: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
f940: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
f950: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
f960: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
f970: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
f980: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
f990: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
f9a0: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
f9b0: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
f9c0: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
f9d0: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
f9e0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
f9f0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
fa00: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
fa10: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
fa20: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
fa30: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
fa40: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
fa50: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
fa60: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
fa70: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
fa80: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
fa90: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
faa0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
fab0: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
fac0: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
fad0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
fae0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
faf0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
fb00: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
fb10: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
fb20: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
fb30: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
fb40: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
fb50: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
fb60: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
fb70: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
fb80: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
fb90: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
fba0: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
fbb0: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
fbc0: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
fbd0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
fbe0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
fbf0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
fc00: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
fc10: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
fc20: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
fc30: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
fc40: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
fc50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
fc60: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
fc70: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
fc80: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
fc90: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
fca0: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
fcb0: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
fcc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
fcd0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
fce0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
fcf0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
fd00: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
fd10: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
fd20: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
fd30: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
fd40: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
fd50: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
fd60: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
fd70: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
fd80: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
fd90: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
fda0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
fdb0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
fdc0: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
fdd0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
fde0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
fdf0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
fe00: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
fe10: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
fe20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
fe30: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
fe40: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
fe50: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
fe60: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
fe70: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
fe80: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
fe90: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
fea0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
feb0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
fec0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
fed0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
fee0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
fef0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ff00: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
ff10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
ff20: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
ff30: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
ff40: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
ff50: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
ff60: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
ff70: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
ff80: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
ff90: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
ffa0: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
ffb0: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
ffc0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
ffd0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
ffe0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
fff0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
10000 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
10010 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
10020 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
10030 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
10040 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
10050 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
10060 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
10070 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
10080 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
10090 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
100a0 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
100b0 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
100c0 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
100d0 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
100e0 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
100f0 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
10100 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
10110 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
10120 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
10130 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
10140 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
10150 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
10160 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
10170 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
10180 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
10190 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
101a0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
101b0 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
101c0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
101d0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
101e0 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
101f0 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
10200 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
10210 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
10220 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
10230 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
10240 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
10250 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
10260 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
10270 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
10280 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
10290 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
102a0 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
102b0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
102c0 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
102d0 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
102e0 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
102f0 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
10300 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
10310 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
10320 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
10330 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
10340 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
10350 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
10360 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
10370 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
10380 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
10390 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
103a0 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
103b0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
103c0 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
103d0 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
103e0 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
103f0 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
10400 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
10410 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
10420 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
10430 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
10440 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
10450 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
10460 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
10470 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
10480 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
10490 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
104a0 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
104b0 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
104c0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
104d0 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
104e0 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
104f0 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
10500 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
10510 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
10520 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
10530 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
10540 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
10550 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
10560 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
10570 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
10580 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
10590 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
105a0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
105b0 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
105c0 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
105d0 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
105e0 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
105f0 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
10600 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
10610 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
10620 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
10630 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
10640 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
10650 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
10660 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
10670 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
10680 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
10690 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
106a0 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
106b0 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
106c0 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
106d0 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
106e0 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
106f0 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
10700 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
10710 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
10720 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
10730 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
10740 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
10750 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
10760 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
10770 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
10780 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
10790 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
107a0 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
107b0 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
107c0 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
107d0 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
107e0 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
107f0 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
10800 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
10810 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
10820 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
10830 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
10840 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
10850 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
10860 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
10870 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
10880 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
10890 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
108a0 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
108b0 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
108c0 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
108d0 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
108e0 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
108f0 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
10900 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
10910 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
10920 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
10930 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
10940 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
10950 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
10960 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
10970 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
10980 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
10990 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
109a0 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
109b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
109c0 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
109d0 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
109e0 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
109f0 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
10a00 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
10a10 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
10a20 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
10a30 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
10a40 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
10a50 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
10a60 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
10a70 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
10a80 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
10a90 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
10aa0 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
10ab0 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
10ac0 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
10ad0 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
10ae0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
10af0 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
10b00 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
10b10 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
10b20 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
10b30 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
10b40 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
10b50 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
10b60 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
10b70 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
10b80 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
10b90 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
10ba0 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
10bb0 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
10bc0 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
10bd0 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
10be0 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
10bf0 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
10c00 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
10c10 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
10c20 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
10c30 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
10c40 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
10c50 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
10c60 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
10c70 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
10c80 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
10c90 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
10ca0 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
10cb0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
10cc0 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
10cd0 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
10ce0 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
10cf0 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
10d00 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
10d10 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
10d20 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
10d30 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
10d40 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
10d50 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
10d60 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
10d70 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
10d80 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
10d90 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
10da0 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
10db0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
10dc0 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
10dd0 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
10de0 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
10df0 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
10e00 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
10e10 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
10e20 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
10e30 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
10e40 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
10e50 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
10e60 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
10e70 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
10e80 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
10e90 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
10ea0 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
10eb0 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
10ec0 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
10ed0 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
10ee0 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
10ef0 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
10f00 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
10f10 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
10f20 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
10f30 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
10f40 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
10f50 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
10f60 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
10f70 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
10f80 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
10f90 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
10fa0 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
10fb0 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
10fc0 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
10fd0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
10fe0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
10ff0 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
11000 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
11010 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
11020 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
11030 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
11040 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
11050 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
11060 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
11070 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
11080 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
11090 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
110a0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
110b0 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
110c0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
110d0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
110e0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
110f0 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
11100 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
11110 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
11120 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
11130 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
11140 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
11150 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
11160 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
11170 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
11180 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
11190 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
111a0 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
111b0 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
111c0 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
111d0 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
111e0 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
111f0 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
11200 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
11210 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
11220 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
11230 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
11240 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
11250 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
11260 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
11270 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
11280 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
11290 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
112a0 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
112b0 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
112c0 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
112d0 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
112e0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
112f0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
11300 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
11310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
11320 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
11330 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
11340 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
11350 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
11360 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
11370 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
11380 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
11390 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
113a0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
113b0 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
113c0 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
113d0 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
113e0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
113f0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
11400 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
11410 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
11420 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
11430 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
11440 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
11450 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
11460 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
11470 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
11480 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
11490 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
114a0 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
114b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
114c0 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
114d0 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
114e0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
114f0 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
11500 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
11510 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
11520 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
11530 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
11540 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
11550 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
11560 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
11570 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
11580 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
11590 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
115a0 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
115b0 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
115c0 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
115d0 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
115e0 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
115f0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
11600 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
11610 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
11620 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
11630 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
11640 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
11650 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
11660 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
11670 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
11680 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
11690 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
116a0 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
116b0 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
116c0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
116d0 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
116e0 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
116f0 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
11700 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
11710 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
11720 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
11730 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
11740 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
11750 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
11760 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
11770 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
11780 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
11790 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
117a0 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
117b0 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
117c0 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
117d0 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
117e0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
117f0 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
11800 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
11810 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
11820 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
11830 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
11840 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
11850 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
11860 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
11870 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
11880 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
11890 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
118a0 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
118b0 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
118c0 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
118d0 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
118e0 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
118f0 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
11900 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
11910 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
11920 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
11930 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
11940 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
11950 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
11960 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
11970 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
11980 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
11990 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
119a0 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
119b0 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
119c0 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
119d0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
119e0 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
119f0 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
11a00 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
11a10 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
11a20 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
11a30 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
11a40 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
11a50 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
11a60 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
11a70 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
11a80 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
11a90 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
11aa0 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
11ab0 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
11ac0 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
11ad0 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
11ae0 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
11af0 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
11b00 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
11b10 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
11b20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
11b30 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
11b40 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
11b50 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
11b60 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
11b70 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
11b80 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
11b90 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
11ba0 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
11bb0 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
11bc0 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
11bd0 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
11be0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
11bf0 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
11c00 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
11c10 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
11c20 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
11c30 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
11c40 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
11c50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
11c60 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
11c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
11c80 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
11c90 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
11ca0 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
11cb0 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
11cc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
11cd0 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
11ce0 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
11cf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11d00 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
11d10 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
11d20 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
11d30 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
11d40 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
11d50 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
11d60 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
11d70 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
11d80 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
11d90 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
11da0 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
11db0 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
11dc0 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
11dd0 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
11de0 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
11df0 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
11e00 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
11e10 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
11e20 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
11e30 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
11e40 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
11e50 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
11e60 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
11e70 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
11e80 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
11e90 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
11ea0 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
11eb0 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
11ec0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
11ed0 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
11ee0 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
11ef0 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
11f00 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
11f10 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
11f20 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
11f30 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
11f40 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
11f50 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
11f60 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
11f70 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
11f80 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
11f90 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
11fa0 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
11fb0 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
11fc0 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
11fd0 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
11fe0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
11ff0 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
12000 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
12010 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
12020 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
12030 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
12040 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
12050 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
12060 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
12070 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
12080 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
12090 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
120a0 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
120b0 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
120c0 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
120d0 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
120e0 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
120f0 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
12100 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
12110 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
12120 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
12130 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
12140 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
12150 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
12160 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
12170 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
12180 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
12190 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
121a0 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
121b0 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
121c0 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
121d0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
121e0 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
121f0 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
12200 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
12210 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
12220 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
12230 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
12240 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
12250 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
12260 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
12270 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
12280 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
12290 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
122a0 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
122b0 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
122c0 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
122d0 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
122e0 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
122f0 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
12300 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
12310 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
12320 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
12330 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
12340 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
12350 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12360 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
12370 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
12380 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
12390 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
123a0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
123b0 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
123c0 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
123d0 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
123e0 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
123f0 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
12400 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
12410 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
12420 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
12430 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12440 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
12450 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
12460 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
12470 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
12480 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
12490 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
124a0 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
124b0 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
124c0 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
124d0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
124e0 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
124f0 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
12500 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
12510 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
12520 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
12530 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
12540 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
12550 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
12560 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
12570 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
12580 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
12590 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
125a0 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
125b0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
125c0 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
125d0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
125e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
125f0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12600 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
12610 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
12620 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
12630 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
12640 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12650 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
12660 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
12670 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
12680 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
12690 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
126a0 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
126b0 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
126c0 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
126d0 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
126e0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
126f0 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
12700 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
12710 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
12720 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
12730 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
12740 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
12750 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
12760 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
12770 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
12780 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
12790 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
127a0 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
127b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
127c0 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
127d0 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
127e0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
127f0 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
12800 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
12810 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12820 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
12830 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
12840 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
12850 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
12860 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
12870 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
12880 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
12890 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
128a0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
128b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
128c0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
128d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
128e0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
128f0 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
12900 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
12910 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
12920 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
12930 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
12940 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
12950 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
12960 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12970 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
12980 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
12990 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
129a0 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
129b0 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
129c0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
129d0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
129e0 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
129f0 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
12a00 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
12a10 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
12a20 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
12a30 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
12a40 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
12a50 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12a60 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
12a70 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
12a80 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
12a90 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
12aa0 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
12ab0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
12ac0 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
12ad0 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
12ae0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
12af0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
12b00 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
12b10 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
12b20 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
12b30 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
12b40 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
12b50 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
12b60 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
12b70 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
12b80 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
12b90 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12ba0 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
12bb0 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
12bc0 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
12bd0 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
12be0 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
12bf0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
12c00 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
12c10 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
12c20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
12c30 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
12c40 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12c50 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
12c60 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
12c70 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
12c80 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
12c90 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
12ca0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
12cb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
12cc0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
12cd0 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
12ce0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
12cf0 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
12d00 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
12d10 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
12d20 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
12d30 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
12d40 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
12d50 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
12d60 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
12d70 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
12d80 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
12d90 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
12da0 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
12db0 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
12dc0 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
12dd0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
12de0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
12df0 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
12e00 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
12e10 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
12e20 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
12e30 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
12e40 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
12e50 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12e60 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
12e70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
12e80 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
12e90 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
12ea0 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
12eb0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
12ec0 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
12ed0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
12ee0 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
12ef0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12f00 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
12f10 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
12f20 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
12f30 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
12f40 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
12f50 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
12f60 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12f70 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
12f80 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
12f90 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
12fa0 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
12fb0 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
12fc0 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
12fd0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
12fe0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
12ff0 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
13000 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
13010 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
13020 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
13030 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
13040 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
13050 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
13060 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
13070 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
13080 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
13090 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
130a0 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
130b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
130c0 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
130d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
130e0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
130f0 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
13100 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
13110 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
13120 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
13130 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
13140 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
13150 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
13160 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
13170 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
13180 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
13190 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
131a0 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
131b0 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ilure..*/.SQLITE
131c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
131d0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
131e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
131f0 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
13200 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  wn(void);.SQLITE
13210 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
13220 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
13230 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
13240 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
13250 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
13260 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
13270 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
13280 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
13290 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
132a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
132b0 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
132c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
132d0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
132e0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
132f0 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
13300 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
13310 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
13320 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
13330 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
13340 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
13350 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
13360 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
13370 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
13380 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
13390 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
133a0 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
133b0 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
133c0 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
133d0 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
133e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
133f0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
13400 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
13410 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
13420 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
13430 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
13440 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
13450 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
13460 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
13470 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
13480 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
13490 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
134a0 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
134b0 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
134c0 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
134d0 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
134e0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
134f0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
13500 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
13510 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
13520 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
13530 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
13540 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
13550 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
13560 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
13570 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
13580 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
13590 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
135a0 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
135b0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
135c0 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
135d0 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
135e0 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
135f0 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
13600 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
13610 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
13620 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
13630 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
13640 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
13650 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
13660 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
13670 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
13680 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
13690 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
136a0 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
136b0 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
136c0 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
136d0 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
136e0 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
136f0 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
13700 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
13710 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
13720 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
13730 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
13740 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
13750 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
13760 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
13770 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
13780 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
13790 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
137a0 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
137b0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
137c0 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
137d0 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
137e0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
137f0 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
13800 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  de]..*/.SQLITE_A
13810 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
13820 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
13830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13840 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
13850 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
13860 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
13870 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
13880 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
13890 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
138a0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
138b0 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
138c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
138d0 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
138e0 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
138f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13900 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
13910 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
13920 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
13930 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13940 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
13950 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
13960 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
13970 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
13980 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
13990 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
139a0 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
139b0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
139c0 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
139d0 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
139e0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
139f0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
13a00 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
13a10 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
13a20 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
13a30 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
13a40 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
13a50 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
13a60 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
13a70 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
13a80 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
13a90 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
13aa0 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
13ab0 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
13ac0 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
13ad0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
13ae0 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  ccessful..*/.SQL
13af0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
13b00 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
13b10 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
13b20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
13b30 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
13b40 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
13b50 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
13b60 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
13b70 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
13b80 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
13b90 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
13ba0 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
13bb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
13bc0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
13bd0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
13be0 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
13bf0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
13c00 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
13c10 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
13c20 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
13c30 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
13c40 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
13c50 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
13c60 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
13c70 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
13c80 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
13c90 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
13ca0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13cb0 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
13cc0 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
13cd0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
13ce0 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
13cf0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
13d00 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
13d10 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
13d20 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
13d30 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
13d40 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
13d50 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
13d60 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
13d70 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
13d80 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
13d90 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
13da0 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
13db0 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
13dc0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
13dd0 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
13de0 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
13df0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13e00 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
13e10 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
13e20 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
13e30 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
13e40 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
13e50 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
13e60 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
13e70 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
13e80 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
13e90 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
13ea0 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
13eb0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13ec0 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
13ed0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
13ee0 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
13ef0 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
13f00 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
13f10 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
13f20 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
13f30 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
13f40 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
13f50 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
13f60 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
13f70 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
13f80 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
13f90 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
13fa0 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
13fb0 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
13fc0 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
13fd0 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
13fe0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
13ff0 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
14000 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
14010 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
14020 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
14030 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
14040 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
14050 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
14060 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
14070 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
14080 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
14090 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
140a0 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
140b0 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
140c0 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
140d0 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
140e0 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
140f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
14100 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
14110 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
14120 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
14130 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
14140 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
14150 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
14160 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
14170 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
14180 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
14190 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
141a0 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
141b0 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
141c0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
141d0 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
141e0 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
141f0 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
14200 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
14210 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14220 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
14230 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
14240 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
14250 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
14260 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
14270 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
14280 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
14290 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
142a0 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
142b0 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
142c0 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
142d0 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
142e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
142f0 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
14300 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
14310 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
14320 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
14330 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
14340 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
14350 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
14360 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
14370 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
14380 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
14390 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
143a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
143b0 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
143c0 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
143d0 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
143e0 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
143f0 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
14400 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
14410 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
14420 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
14430 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
14440 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
14450 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
14460 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
14470 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
14480 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
14490 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
144a0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
144b0 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
144c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
144d0 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
144e0 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
144f0 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
14500 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
14510 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
14520 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
14530 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
14540 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
14550 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
14560 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
14570 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
14580 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
14590 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
145a0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
145b0 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
145c0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
145d0 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
145e0 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
145f0 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
14600 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
14610 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
14620 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
14630 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
14640 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
14650 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
14660 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
14670 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
14680 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
14690 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
146a0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
146b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
146c0 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
146d0 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
146e0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
146f0 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
14700 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
14710 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
14720 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
14730 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
14740 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
14750 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
14760 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
14770 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
14780 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
14790 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
147a0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
147b0 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
147c0 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
147d0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
147e0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
147f0 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
14800 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
14810 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
14820 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
14830 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
14840 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
14850 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
14860 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
14870 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
14880 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
14890 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
148a0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
148b0 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
148c0 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
148d0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
148e0 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
148f0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
14900 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
14910 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
14920 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
14930 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
14940 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
14950 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
14960 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
14970 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
14980 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
14990 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
149a0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
149b0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
149c0 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
149d0 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
149e0 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
149f0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
14a00 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
14a10 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
14a20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
14a30 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
14a40 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
14a50 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
14a60 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
14a70 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
14a80 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
14a90 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14aa0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
14ab0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
14ac0 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
14ad0 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
14ae0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
14af0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
14b00 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
14b10 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
14b20 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
14b30 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
14b40 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
14b50 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
14b60 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
14b70 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
14b80 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
14b90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14ba0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
14bb0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
14bc0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
14bd0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
14be0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
14bf0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14c00 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
14c10 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
14c20 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
14c30 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14c40 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
14c50 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
14c60 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
14c70 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
14c80 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
14c90 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
14ca0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
14cb0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
14cc0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
14cd0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
14ce0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
14cf0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
14d00 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
14d10 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
14d20 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
14d30 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
14d40 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
14d50 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
14d60 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
14d70 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
14d80 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
14d90 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
14da0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
14db0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
14dc0 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
14dd0 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
14de0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
14df0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
14e00 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
14e10 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
14e20 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
14e30 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
14e40 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14e50 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
14e60 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
14e70 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
14e80 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
14e90 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
14ea0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
14eb0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
14ec0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14ed0 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
14ee0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
14ef0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
14f00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14f10 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
14f20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14f30 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
14f40 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14f50 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
14f60 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14f70 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
14f80 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
14f90 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
14fa0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
14fb0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
14fc0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
14fd0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
14fe0 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
14ff0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
15000 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
15010 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
15020 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
15030 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
15040 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
15050 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
15060 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
15070 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
15080 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
15090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
150a0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
150b0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
150c0 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
150d0 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
150e0 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
150f0 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
15100 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
15110 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
15120 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
15130 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
15140 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
15150 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
15160 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15170 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
15180 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
15190 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
151a0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
151b0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
151c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
151d0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
151e0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
151f0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
15200 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
15210 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
15220 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
15230 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
15240 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
15250 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
15260 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
15270 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
15280 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
15290 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
152a0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
152b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
152c0 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
152d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
152e0 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
152f0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
15300 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
15310 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
15320 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
15330 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
15340 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
15350 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
15360 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
15370 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
15380 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
15390 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
153a0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
153b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
153c0 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
153d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
153e0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
153f0 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
15400 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
15410 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
15420 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
15430 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
15440 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
15450 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
15460 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
15470 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
15480 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15490 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
154a0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
154b0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
154c0 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
154d0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
154e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
154f0 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
15500 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
15510 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
15520 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
15530 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
15540 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
15550 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
15560 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
15570 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
15580 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
15590 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
155a0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
155b0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
155c0 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
155d0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
155e0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
155f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15600 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
15610 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
15620 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
15630 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
15640 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
15650 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
15660 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
15680 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
15690 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
156a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
156b0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
156c0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
156d0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
156e0 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
156f0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
15700 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
15710 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
15720 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
15730 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
15740 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
15750 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15760 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
15770 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
15780 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
15790 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
157a0 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
157b0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
157c0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
157d0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
157e0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
157f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
15800 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15810 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
15820 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
15830 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
15840 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
15850 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15860 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
15870 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15880 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
15890 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
158a0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
158b0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
158c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
158d0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
158e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
158f0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
15900 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
15910 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
15920 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
15930 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
15940 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
15950 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
15960 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
15970 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
15980 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
15990 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
159a0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
159b0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
159c0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
159d0 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
159e0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
159f0 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
15a00 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
15a10 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
15a20 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
15a30 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15a40 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
15a50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
15a60 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
15a70 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
15a80 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
15a90 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
15aa0 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
15ab0 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
15ac0 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
15ad0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
15ae0 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
15af0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15b00 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
15b10 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
15b20 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
15b30 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
15b40 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
15b50 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
15b60 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
15b70 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
15b80 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
15b90 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
15ba0 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
15bb0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
15bc0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
15bd0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
15be0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
15bf0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
15c00 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
15c10 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
15c20 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
15c30 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
15c40 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
15c50 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
15c60 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
15c70 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
15c80 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
15c90 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
15ca0 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
15cb0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
15cc0 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
15cd0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
15ce0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
15cf0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15d00 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
15d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
15d20 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
15d30 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
15d40 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
15d50 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
15d60 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
15d70 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
15d80 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
15d90 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
15da0 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
15db0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
15dc0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
15dd0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
15de0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
15df0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
15e00 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
15e10 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
15e20 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
15e30 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
15e40 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
15e50 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
15e60 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
15e70 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
15e80 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
15e90 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
15ea0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
15eb0 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
15ec0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
15ed0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
15ee0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
15ef0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
15f00 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
15f10 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
15f20 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
15f30 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
15f40 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
15f50 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
15f60 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
15f70 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
15f80 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
15f90 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
15fa0 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
15fb0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
15fc0 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
15fd0 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
15fe0 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
15ff0 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
16000 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
16010 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
16020 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
16030 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
16040 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
16050 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
16060 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16070 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
16080 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
16090 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
160a0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
160b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
160c0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
160d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
160e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
160f0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
16100 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
16110 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
16120 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
16130 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
16140 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
16150 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
16160 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
16170 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
16180 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
16190 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
161a0 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
161b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
161c0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
161d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
161e0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
161f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16200 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ACHE2 option..**
16210 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
16220 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
16230 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
16240 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
16250 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
16260 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
16270 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
16280 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
16290 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
162a0 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
162b0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
162c0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
162d0 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
162e0 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
162f0 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
16300 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
16310 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
16320 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
16330 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
16340 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
16350 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
16360 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
16370 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
16380 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
16390 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
163a0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
163b0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
163c0 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
163d0 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
163e0 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
163f0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
16400 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
16410 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
16420 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
16430 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
16440 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
16450 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
16460 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
16470 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
16480 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
16490 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
164a0 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
164b0 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
164c0 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
164d0 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
164e0 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
164f0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
16500 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
16510 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
16520 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
16530 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
16540 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
16550 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
16560 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
16570 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
16580 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
16590 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
165a0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
165b0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
165c0 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
165d0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
165e0 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
165f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16600 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
16610 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
16620 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
16630 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
16640 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
16650 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
16660 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
16670 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
16680 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
16690 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
166a0 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
166b0 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
166c0 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
166d0 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
166e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
166f0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
16700 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
16710 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
16720 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
16730 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
16740 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
16750 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
16760 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
16770 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
16780 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
16790 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
167a0 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
167b0 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
167c0 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
167d0 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
167e0 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
167f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
16800 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
16810 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
16820 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
16830 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
16840 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
16850 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
16860 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
16870 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
16880 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
16890 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
168a0 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
168b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
168c0 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
168d0 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
168e0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
168f0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
16900 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
16910 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
16920 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
16930 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
16940 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
16950 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
16960 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
16970 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
16980 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
16990 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
169a0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
169b0 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
169c0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
169d0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
169e0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
169f0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
16a00 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
16a10 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
16a20 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
16a30 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
16a40 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
16a50 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
16a60 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
16a70 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
16a80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
16a90 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
16aa0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
16ab0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
16ac0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
16ad0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
16ae0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
16af0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
16b00 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
16b10 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
16b20 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
16b30 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
16b40 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
16b50 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
16b60 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
16b70 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
16b80 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
16b90 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
16ba0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
16bb0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16bc0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
16bd0 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
16be0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
16bf0 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
16c00 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
16c10 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
16c20 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
16c30 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
16c40 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
16c50 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16c60 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
16c70 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
16c80 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
16c90 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
16ca0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
16cb0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
16cc0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
16cd0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
16ce0 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
16cf0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
16d00 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
16d10 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
16d20 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16d30 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
16d40 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
16d50 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
16d60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
16d70 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
16d80 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
16d90 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
16da0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
16db0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
16dc0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
16dd0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
16de0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
16df0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
16e00 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
16e10 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
16e20 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
16e30 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
16e40 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
16e50 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
16e60 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
16e70 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
16e80 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
16e90 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
16ea0 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
16eb0 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
16ec0 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
16ed0 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
16ee0 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
16ef0 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
16f00 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
16f10 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
16f20 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
16f30 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
16f40 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
16f50 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
16f60 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
16f70 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
16f80 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
16f90 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
16fa0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
16fb0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
16fc0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
16fd0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
16fe0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16ff0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
17000 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
17010 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
17020 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
17030 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
17040 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17050 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
17060 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
17070 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
17080 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
17090 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
170a0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
170b0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
170c0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
170d0 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
170e0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
170f0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
17100 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
17110 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
17120 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
17130 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
17140 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
17150 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
17160 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
17170 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
17180 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
17190 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
171a0 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
171b0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
171c0 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
171d0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
171e0 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
171f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
17200 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
17210 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
17220 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
17230 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
17240 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
17250 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
17260 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17270 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
17280 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17290 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
172a0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
172b0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
172c0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
172d0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
172e0 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
172f0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
17300 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
17310 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
17320 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
17330 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
17340 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
17350 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53  mentation.)^  ^S
17360 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
17370 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
17380 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
17390 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
173a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
173b0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
173c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
173d0 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
173e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
173f0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
17400 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
17410 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
17420 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
17430 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17440 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
17450 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
17460 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
17470 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
17480 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
17490 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
174a0 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
174b0 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
174c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
174d0 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
174e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
174f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
17500 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17510 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
17520 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
17530 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
17540 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
17550 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
17560 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
17570 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
17580 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
17590 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
175a0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
175b0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
175c0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
175d0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
175e0 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
175f0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
17600 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
17610 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
17620 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
17630 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
17640 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
17650 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
17660 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
17670 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
17680 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
17690 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
176a0 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
176b0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
176c0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
176d0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
176e0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
176f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
17700 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
17710 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
17720 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
17730 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
17740 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
17750 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
17760 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
17770 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
17780 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
17790 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
177a0 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
177b0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
177c0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
177d0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
177e0 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
177f0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
17800 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
17810 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
17820 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
17830 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
17840 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
17850 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
17860 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
17870 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
17880 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
17890 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
178a0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
178b0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
178c0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
178d0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
178e0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
178f0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
17900 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
17910 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
17920 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
17930 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
17940 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
17950 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
17960 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17970 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73  URI.** <dd> This
17980 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17990 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
179a0 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
179b0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
179c0 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
179d0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
179e0 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
179f0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
17a00 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
17a10 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
17a20 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20  isabled. If URI 
17a30 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
17a40 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c  ally enabled, al
17a50 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70  l filenames.** p
17a60 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
17a70 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
17a80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
17a90 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
17aa0 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
17ab0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
17ac0 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
17ad0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
17ae0 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
17af0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
17b00 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
17b10 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
17b20 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
17b30 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
17b40 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
17b50 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67  ened. If it is g
17b60 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
17b70 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
17b80 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
17b90 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
17ba0 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
17bb0 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
17bc0 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
17bd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
17be0 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66  s opened. By def
17bf0 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
17c00 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
17c10 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
17c20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
17c30 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
17c40 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
17c50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
17c60 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
17c70 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fined..**.** [[S
17c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17c90 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
17ca0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
17cb0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
17cc0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
17cd0 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
17ce0 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
17cf0 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
17d00 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
17d10 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
17d20 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
17d30 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
17d40 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
17d50 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
17d60 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
17d70 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  -ops..** </dl>.*
17d80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17d90 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
17da0 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
17db0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17dc0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
17dd0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
17de0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17df0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
17e00 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
17e10 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
17e20 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
17e30 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
17e40 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
17e50 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
17e60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17e70 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
17e80 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
17e90 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
17ea0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17eb0 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
17ec0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
17ed0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
17ee0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17ef0 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
17f00 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
17f10 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
17f20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17f30 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
17f40 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
17f50 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
17f60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17f70 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
17f80 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
17f90 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
17fa0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17fb0 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
17fc0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
17fd0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
17fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17ff0 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
18000 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
18010 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
18020 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
18030 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
18040 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
18050 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
18060 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
18070 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
18080 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
18090 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
180a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
180b0 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
180c0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
180d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
180e0 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
180f0 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
18100 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18110 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
18120 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
18130 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
18140 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
18150 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
18160 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
18170 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18180 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
18190 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
181a0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
181b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
181c0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
181d0 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
181e0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
181f0 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  2* */../*.** CAP
18200 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
18210 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
18220 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
18230 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
18240 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
18250 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
18260 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
18270 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
18280 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
18290 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
182a0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
182b0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
182c0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
182d0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
182e0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
182f0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
18300 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
18310 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
18320 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
18330 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
18340 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
18350 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
18360 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
18370 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
18380 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
18390 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
183a0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
183b0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
183c0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
183d0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
183e0 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
183f0 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
18400 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
18410 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
18420 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
18430 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
18440 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
18450 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
18460 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18470 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
18480 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
18490 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
184a0 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
184b0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
184c0 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
184d0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
184e0 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
184f0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
18500 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
18510 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
18520 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18530 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
18540 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
18550 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
18560 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
18570 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
18580 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
18590 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
185a0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
185b0 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
185c0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
185d0 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
185e0 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
185f0 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
18600 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
18610 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
18620 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
18630 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
18640 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
18650 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
18660 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
18670 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
18680 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
18690 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
186a0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
186b0 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
186c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
186d0 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
186e0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
186f0 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
18700 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
18710 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
18720 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
18730 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
18740 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
18750 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
18760 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
18770 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
18780 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
18790 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
187a0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
187b0 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
187c0 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
187d0 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
187e0 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
187f0 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
18800 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
18810 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
18820 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
18830 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
18840 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
18850 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
18860 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
18870 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
18880 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
18890 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
188a0 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
188b0 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
188c0 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
188d0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
188e0 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
188f0 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
18900 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
18910 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
18920 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
18930 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
18940 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
18950 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
18960 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
18970 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
18980 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
18990 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
189a0 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
189b0 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
189c0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
189d0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
189e0 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
189f0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
18a00 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
18a10 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
18a20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
18a30 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
18a40 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
18a50 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
18a60 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18a70 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
18a80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18a90 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18aa0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18ab0 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
18ac0 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
18ad0 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
18ae0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
18af0 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
18b00 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
18b10 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
18b20 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18b30 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18b40 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
18b50 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
18b60 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
18b70 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
18b80 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
18b90 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
18ba0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
18bb0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
18bc0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
18bd0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
18be0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
18bf0 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
18c00 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
18c10 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
18c20 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
18c30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18c40 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
18c50 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
18c60 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
18c70 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
18c80 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
18c90 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
18ca0 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
18cb0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
18cc0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
18cd0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
18ce0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
18cf0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
18d00 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
18d10 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
18d20 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
18d30 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
18d40 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
18d50 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
18d60 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
18d70 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18d80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18d90 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18da0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18db0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18dc0 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
18dd0 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
18de0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
18df0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
18e00 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
18e10 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
18e20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
18e30 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
18e40 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
18e50 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
18e60 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
18e70 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
18e80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18e90 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18ea0 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f  DE       1001  /
18eb0 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
18ec0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18ed0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18ee0 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20  E_FKEY     1002 
18ef0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
18f00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18f10 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
18f20 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a  RIGGER  1003  /*
18f30 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f   int int* */.../
18f40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
18f50 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
18f60 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
18f70 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Codes.**.** ^Th
18f80 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
18f90 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
18fa0 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
18fb0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
18fc0 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
18fd0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
18fe0 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
18ff0 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
19000 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
19010 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
19020 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
19030 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
19040 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ty..*/.SQLITE_AP
19050 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
19060 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
19070 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
19080 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
19090 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
190a0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
190b0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
190c0 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
190d0 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
190e0 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
190f0 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
19100 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
19110 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
19120 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
19130 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
19140 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
19150 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
19160 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
19170 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
19180 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
19190 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
191a0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
191b0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
191c0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
191d0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
191e0 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
191f0 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
19200 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
19210 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
19220 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
19230 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
19240 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
19250 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
19260 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
19270 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
19280 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
19290 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
192a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
192b0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
192c0 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f  argument.  ^As o
192d0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
192e0 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75   3.7.7, this rou
192f0 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73  tines.** records
19300 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
19310 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f   rowid of both o
19320 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61  rdinary tables a
19330 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  nd [virtual tabl
19340 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  es]..** ^If no s
19350 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
19360 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  T]s.** have ever
19370 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
19380 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
19390 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
193a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
193b0 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
193c0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
193d0 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69  trigger or withi
193e0 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  n a [virtual tab
193f0 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74  le].** method, t
19400 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
19410 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
19420 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
19430 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
19440 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
19450 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
19460 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69  l table method i
19470 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
19480 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
19490 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
194a0 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c  ble method ends,
194b0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
194c0 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
194d0 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
194e0 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
194f0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
19500 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20  r or virtual.** 
19510 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67  table method beg
19520 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  an.)^.**.** ^An 
19530 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
19540 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
19550 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
19560 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
19570 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
19580 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
19590 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
195a0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
195b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
195c0 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
195d0 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
195e0 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
195f0 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
19600 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
19610 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
19620 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
19630 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
19640 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
19650 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
19660 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
19670 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
19680 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
19690 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
196a0 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
196b0 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
196c0 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
196d0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
196e0 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
196f0 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
19700 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
19710 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
19720 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
19730 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
19740 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
19750 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
19760 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
19770 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
19780 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
19790 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
197a0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
197b0 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
197c0 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
197d0 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
197e0 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
197f0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
19800 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
19810 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
19820 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
19830 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
19840 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
19850 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
19860 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
19870 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
19880 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
19890 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
198a0 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
198b0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
198c0 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
198d0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
198e0 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
198f0 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
19900 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
19910 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19920 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
19930 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19940 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
19950 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
19960 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
19970 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
19980 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
19990 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
199a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
199b0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
199c0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
199d0 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
199e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
199f0 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
19a00 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
19a10 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
19a20 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
19a30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
19a40 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
19a50 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
19a60 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
19a70 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
19a80 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
19a90 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
19aa0 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
19ab0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19ac0 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
19ad0 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
19ae0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79  meter..** ^(Only
19af0 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
19b00 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
19b10 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
19b20 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
19b30 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
19b40 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
19b50 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
19b60 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
19b70 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
19b80 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
19b90 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
19ba0 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74  counted.)^ Use t
19bb0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
19bc0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
19bd0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64  function to find
19be0 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
19bf0 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20  r of changes.** 
19c00 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
19c10 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
19c20 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e  gers and foreign
19c30 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a   key actions..**
19c40 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  .** ^Changes to 
19c50 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
19c60 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20  simulated by an 
19c70 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
19c80 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ger].** are not 
19c90 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72  counted.  Only r
19ca0 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65  eal table change
19cb0 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
19cc0 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68  *.** ^(A "row ch
19cd0 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
19ce0 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
19cf0 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
19d00 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
19d10 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
19d20 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
19d30 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
19d40 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
19d50 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
19d60 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20  ts of [REPLACE] 
19d70 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
19d80 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
19d90 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
19da0 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c  sing, [DROP TABL
19db0 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  E], or by any ot
19dc0 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
19dd0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
19de0 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
19df0 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  nges.)^.**.** A 
19e00 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
19e10 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
19e20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
19e30 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
19e40 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
19e50 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
19e60 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
19e70 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
19e80 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
19e90 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
19ea0 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
19eb0 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
19ec0 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
19ed0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
19ee0 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
19ef0 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
19f00 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
19f10 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
19f20 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
19f30 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
19f40 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
19f50 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
19f60 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
19f70 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
19f80 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
19f90 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65  ^Calling [sqlite
19fa0 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
19fb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
19fc0 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
19fd0 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
19fe0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
19ff0 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  xt..**.** ^This 
1a000 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a010 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
1a020 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
1a030 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
1a040 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
1a050 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
1a060 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1a070 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
1a080 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
1a090 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65  **.** ^Thus, whe
1a0a0 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
1a0b0 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
1a0c0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1a0d0 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
1a0e0 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
1a0f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
1a100 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
1a110 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
1a120 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
1a130 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
1a140 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62    ^(Within the b
1a150 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
1a160 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
1a170 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
1a180 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  face can be call
1a190 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
1a1a0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
1a1b0 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
1a1c0 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
1a1d0 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
1a1e0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1a1f0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1a200 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
1a210 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
1a220 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
1a230 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
1a240 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1a250 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
1a260 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
1a270 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76   since those hav
1a280 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
1a290 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ext.)^.**.** See
1a2a0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
1a2b0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1a2c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
1a2d0 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
1a2e0 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
1a2f0 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
1a300 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1a310 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1a320 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
1a330 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
1a340 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1a350 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
1a360 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1a370 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1a380 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
1a390 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
1a3a0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1a3b0 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1a3c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1a3d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
1a3e0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1a3f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1a400 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
1a410 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
1a420 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1a430 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
1a440 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
1a450 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
1a460 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
1a470 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
1a480 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
1a490 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1a4a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
1a4b0 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
1a4c0 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
1a4d0 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
1a4e0 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
1a4f0 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
1a500 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
1a510 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
1a520 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
1a530 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
1a540 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
1a550 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
1a560 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
1a570 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
1a580 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
1a590 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
1a5a0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
1a5b0 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
1a5c0 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
1a5d0 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
1a5e0 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
1a5f0 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
1a600 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
1a610 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
1a620 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
1a630 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
1a640 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
1a650 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
1a660 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
1a670 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
1a680 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
1a690 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
1a6a0 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
1a6b0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1a6c0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
1a6d0 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
1a6e0 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
1a6f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
1a700 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
1a710 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
1a720 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
1a730 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
1a740 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
1a750 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
1a760 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
1a770 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
1a780 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
1a790 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
1a7a0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
1a7b0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
1a7c0 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
1a7d0 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
1a7e0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
1a7f0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1a800 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1a810 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1a820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a830 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1a840 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1a850 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1a860 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
1a870 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
1a880 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1a890 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1a8a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1a8b0 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
1a8c0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1a8d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1a8e0 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
1a8f0 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
1a900 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
1a910 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
1a920 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
1a930 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
1a940 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
1a950 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
1a960 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
1a970 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
1a980 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
1a990 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
1a9a0 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
1a9b0 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
1a9c0 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
1a9d0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
1a9e0 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
1a9f0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
1aa00 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
1aa10 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
1aa20 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
1aa30 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1aa40 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
1aa50 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
1aa60 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
1aa70 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
1aa80 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
1aa90 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1aaa0 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
1aab0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
1aac0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
1aad0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1aae0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
1aaf0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
1ab00 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
1ab10 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
1ab20 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
1ab30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
1ab40 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
1ab50 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
1ab60 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
1ab70 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
1ab80 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
1ab90 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
1aba0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
1abb0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
1abc0 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
1abd0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
1abe0 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
1abf0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
1ac00 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
1ac10 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
1ac20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
1ac30 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
1ac40 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
1ac50 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
1ac60 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
1ac70 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1ac80 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
1ac90 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
1aca0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
1acb0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
1acc0 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
1acd0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
1ace0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
1acf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ad00 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1ad10 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
1ad20 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
1ad30 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
1ad40 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1ad50 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
1ad60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
1ad70 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
1ad80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1ad90 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1ada0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1adb0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1adc0 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
1add0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
1ade0 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
1adf0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
1ae00 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
1ae10 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
1ae20 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
1ae30 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
1ae40 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
1ae50 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
1ae60 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1ae70 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1ae80 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
1ae90 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
1aea0 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
1aeb0 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
1aec0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1aed0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
1aee0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
1aef0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
1af00 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
1af10 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
1af20 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1af30 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
1af40 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
1af50 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
1af60 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1af70 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1af80 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1af90 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
1afa0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
1afb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1afc0 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
1afd0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
1afe0 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
1aff0 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
1b000 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
1b010 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  happen..*/.SQLIT
1b020 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1b030 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
1b040 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1b050 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
1b060 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
1b070 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
1b080 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
1b090 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
1b0a0 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
1b0b0 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
1b0c0 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
1b0d0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
1b0e0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
1b0f0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
1b100 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1b110 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
1b120 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
1b130 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
1b140 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
1b150 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
1b160 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
1b170 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1b180 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
1b190 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
1b1a0 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
1b1b0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1b1c0 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
1b1d0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
1b1e0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
1b1f0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
1b200 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
1b210 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
1b220 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
1b230 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
1b240 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
1b250 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
1b260 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
1b270 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
1b280 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
1b290 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
1b2a0 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
1b2b0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
1b2c0 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
1b2d0 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
1b2e0 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
1b2f0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
1b300 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
1b310 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
1b320 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
1b330 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
1b340 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
1b350 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
1b360 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
1b370 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
1b380 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
1b390 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1b3a0 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
1b3b0 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
1b3c0 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
1b3d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1b3e0 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
1b3f0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
1b400 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
1b410 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
1b420 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
1b430 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
1b440 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
1b450 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
1b460 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
1b470 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
1b480 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
1b490 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
1b4a0 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
1b4b0 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
1b4c0 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
1b4d0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1b4e0 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
1b4f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
1b500 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
1b510 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
1b520 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b530 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
1b540 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
1b550 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
1b560 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
1b570 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b580 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
1b590 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
1b5a0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1b5b0 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
1b5c0 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
1b5d0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
1b5e0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1b5f0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
1b600 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1b610 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
1b620 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
1b630 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1b640 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
1b650 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1b660 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1b670 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
1b680 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1b690 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1b6a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1b6b0 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
1b6c0 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  sql);.SQLITE_API
1b6d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d   int sqlite3_com
1b6e0 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
1b6f0 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
1b700 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
1b710 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
1b720 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
1b730 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a  BUSY Errors.**.*
1b740 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1b750 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
1b760 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
1b770 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1b780 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
1b790 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1b7a0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
1b7b0 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
1b7c0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
1b7d0 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
1b7e0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ked..**.** ^If t
1b7f0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1b800 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
1b810 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
1b820 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
1b830 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
1b840 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1b850 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
1b860 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
1b870 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1b880 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1b890 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1b8a0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1b8b0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1b8c0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1b8d0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1b8e0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1b8f0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1b900 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1b910 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1b920 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1b930 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1b940 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1b950 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1b960 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1b970 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1b980 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1b990 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1b9a0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1b9b0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1b9c0 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
1b9d0 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
1b9e0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
1b9f0 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
1ba00 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
1ba10 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
1ba20 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
1ba30 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
1ba40 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
1ba50 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
1ba60 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
1ba70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
1ba80 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
1ba90 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1baa0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
1bab0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
1bac0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
1bad0 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
1bae0 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
1baf0 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
1bb00 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
1bb10 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
1bb20 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
1bb30 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
1bb40 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
1bb50 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
1bb60 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
1bb70 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
1bb80 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
1bb90 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
1bba0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
1bbb0 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
1bbc0 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
1bbd0 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
1bbe0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1bbf0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
1bc00 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
1bc10 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
1bc20 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1bc30 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
1bc40 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
1bc50 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1bc60 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
1bc70 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
1bc80 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
1bc90 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
1bca0 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
1bcb0 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
1bcc0 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
1bcd0 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
1bce0 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
1bcf0 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
1bd00 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
1bd10 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
1bd20 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
1bd30 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1bd40 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
1bd50 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
1bd60 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
1bd70 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
1bd80 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1bd90 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
1bda0 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
1bdb0 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
1bdc0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
1bdd0 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
1bde0 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
1bdf0 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
1be00 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
1be10 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
1be20 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
1be30 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
1be40 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
1be50 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
1be60 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
1be70 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
1be80 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
1be90 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1bea0 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
1beb0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1bec0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1bed0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
1bee0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
1bef0 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
1bf00 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
1bf10 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
1bf20 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
1bf30 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
1bf40 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
1bf50 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
1bf60 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
1bf70 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
1bf80 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
1bf90 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
1bfa0 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
1bfb0 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
1bfc0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
1bfd0 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
1bfe0 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
1bff0 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
1c000 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
1c010 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
1c020 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
1c030 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
1c040 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
1c050 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
1c060 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69   readers.  ^If i
1c070 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
1c080 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
1c090 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
1c0a0 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
1c0b0 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
1c0c0 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
1c0d0 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
1c0e0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
1c0f0 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
1c100 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
1c110 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
1c120 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
1c130 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
1c140 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
1c150 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65  ^This error code
1c160 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
1c170 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
1c180 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
1c190 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
1c1a0 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
1c1b0 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
1c1c0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
1c1d0 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
1c1e0 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
1c1f0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
1c200 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
1c210 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
1c220 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
1c230 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
1c240 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1c250 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1c260 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
1c270 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
1c280 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c290 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
1c2a0 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
1c2b0 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
1c2c0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
1c2d0 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
1c2e0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
1c2f0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1c300 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
1c310 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
1c320 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1c330 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
1c340 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
1c350 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
1c360 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
1c370 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
1c380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1c390 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1c3a0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41  busy handler.  A
1c3b0 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
1c3c0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
1c3d0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
1c3e0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
1c3f0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
1c400 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
1c410 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1c420 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
1c430 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
1c440 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1c450 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54  andler..*/.SQLIT
1c460 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1c470 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1c480 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
1c490 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
1c4a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1c4b0 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1c4c0 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
1c4d0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
1c4e0 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
1c4f0 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
1c500 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
1c510 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
1c520 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
1c530 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
1c540 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
1c550 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
1c560 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
1c570 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
1c580 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1c590 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1c5a0 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
1c5b0 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
1c5c0 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
1c5d0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1c5e0 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
1c5f0 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
1c600 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
1c610 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
1c620 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
1c630 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
1c640 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
1c650 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
1c660 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
1c670 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
1c680 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
1c690 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
1c6a0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
1c6b0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
1c6c0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1c6d0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1c6e0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1c6f0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
1c700 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1c710 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
1c720 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
1c730 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
1c740 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
1c750 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
1c760 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1c770 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
1c780 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1c790 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1c7a0 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1c7b0 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1c7c0 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
1c7d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73   int sqlite3_bus
1c7e0 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
1c7f0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
1c800 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1c810 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
1c820 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
1c830 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69  ueries.**.** Thi
1c840 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
1c850 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
1c860 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
1c870 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1c880 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
1c890 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1c8a0 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
1c8b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
1c8c0 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
1c8d0 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
1c8e0 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
1c8f0 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
1c900 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1c910 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
1c920 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
1c930 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
1c940 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
1c950 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
1c960 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
1c970 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
1c980 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
1c990 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
1c9a0 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
1c9b0 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
1c9c0 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
1c9d0 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
1c9e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
1c9f0 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
1ca00 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
1ca10 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
1ca20 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
1ca30 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
1ca40 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
1ca50 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
1ca60 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1ca70 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
1ca80 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1ca90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1caa0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1cab0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1cac0 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1cad0 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1cae0 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1caf0 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1cb00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1cb10 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1cb20 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1cb30 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1cb40 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1cb50 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1cb60 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1cb70 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1cb80 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1cb90 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1cba0 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1cbb0 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1cbc0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1cbd0 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1cbe0 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1cbf0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1cc00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1cc10 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1cc20 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1cc30 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1cc40 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1cc50 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1cc60 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1cc70 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1cc80 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1cc90 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1cca0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1ccb0 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1ccc0 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1ccd0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1cce0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1ccf0 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1cd00 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1cd10 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1cd20 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1cd30 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1cd40 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1cd50 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1cd60 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1cd70 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1cd80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1cd90 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1cda0 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1cdb0 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1cdc0 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1cdd0 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1cde0 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1cdf0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1ce00 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1ce10 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1ce20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1ce30 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1ce40 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1ce50 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1ce60 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1ce70 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1ce80 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1ce90 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1cea0 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1ceb0 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1cec0 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1ced0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1cee0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1cef0 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1cf00 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1cf10 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1cf20 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1cf30 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1cf40 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1cf50 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1cf60 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1cf70 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1cf80 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1cf90 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1cfa0 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1cfb0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1cfc0 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1cfd0 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1cfe0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1cff0 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1d000 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1d010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d020 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1d030 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1d040 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1d050 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1d060 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1d070 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1d080 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1d090 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
1d0a0 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
1d0b0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
1d0c0 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
1d0d0 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
1d0e0 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
1d0f0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1d100 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
1d110 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
1d120 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
1d130 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
1d140 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
1d150 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
1d160 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
1d170 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
1d180 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
1d190 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
1d1a0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1d1b0 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
1d1c0 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
1d1d0 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
1d1e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d1f0 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
1d200 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d210 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
1d220 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
1d230 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
1d240 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
1d250 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
1d260 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
1d270 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
1d280 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
1d290 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
1d2a0 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
1d2b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1d2c0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
1d2d0 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
1d2e0 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
1d2f0 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
1d300 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
1d310 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1d320 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
1d330 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
1d340 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
1d350 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
1d360 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
1d370 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
1d380 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
1d390 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
1d3a0 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
1d3b0 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
1d3c0 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
1d3d0 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
1d3e0 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
1d3f0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
1d400 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
1d410 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
1d420 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
1d430 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
1d440 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1d450 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1d460 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
1d470 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1d480 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d490 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1d4a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1d4b0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1d4c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1d4d0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1d4e0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1d4f0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1d500 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1d510 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1d520 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1d530 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1d540 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1d550 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1d560 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1d570 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1d580 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1d590 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1d5a0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1d5b0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1d5c0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1d5d0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1d5e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1d5f0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
1d600 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1d610 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1d620 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1d630 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1d640 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1d650 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1d660 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1d670 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1d680 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1d690 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1d6a0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1d6b0 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
1d6c0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1d6d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
1d6e0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
1d6f0 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
1d700 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
1d710 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1d720 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1d730 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
1d740 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1d750 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
1d760 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
1d770 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
1d780 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1d790 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
1d7a0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
1d7b0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
1d7c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1d7d0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1d7e0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1d7f0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1d800 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1d810 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1d820 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d830 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1d840 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1d850 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1d860 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1d870 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1d880 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1d890 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1d8a0 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1d8b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1d8c0 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1d8d0 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1d8e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1d8f0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1d900 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1d910 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1d920 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1d930 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1d940 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1d950 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1d960 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1d970 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1d980 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1d990 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1d9a0 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1d9b0 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1d9c0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1d9d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1d9e0 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1d9f0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1da00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1da10 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1da20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1da30 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1da40 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1da50 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1da60 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1da70 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1da80 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1da90 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1daa0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1dab0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1dac0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1dad0 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1dae0 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1daf0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1db00 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1db10 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1db20 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1db30 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1db40 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1db50 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1db60 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1db70 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1db80 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1db90 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1dba0 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1dbb0 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1dbc0 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1dbd0 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1dbe0 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1dbf0 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1dc00 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1dc10 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1dc20 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1dc30 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1dc40 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1dc50 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1dc60 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1dc70 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1dc80 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1dc90 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1dca0 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
1dcb0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
1dcc0 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
1dcd0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
1dce0 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
1dcf0 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
1dd00 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
1dd10 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
1dd20 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
1dd30 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
1dd40 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
1dd50 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
1dd60 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
1dd70 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1dd80 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1dd90 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1dda0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1ddb0 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1ddc0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1ddd0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1dde0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1ddf0 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1de00 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1de10 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1de20 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1de30 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1de40 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1de50 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1de60 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1de70 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1de80 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1de90 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1dea0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1deb0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1dec0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1ded0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1dee0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1def0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1df00 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1df10 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1df20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1df30 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1df40 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1df50 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1df60 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1df70 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1df80 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1df90 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1dfa0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1dfb0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1dfc0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1dfd0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1dfe0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1dff0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1e000 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1e010 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1e020 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1e030 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1e040 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1e050 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1e060 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1e070 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1e080 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1e090 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1e0a0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1e0b0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1e0c0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1e0d0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e0e0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1e0f0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1e100 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1e110 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1e120 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e130 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1e140 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1e150 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1e160 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1e170 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1e180 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1e190 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1e1a0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1e1b0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1e1c0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1e1d0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1e1e0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e1f0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1e200 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1e210 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1e220 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1e230 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1e240 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1e250 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1e260 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1e270 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1e280 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1e290 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1e2a0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1e2b0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1e2c0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1e2d0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1e2e0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1e2f0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1e300 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1e310 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1e320 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1e330 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1e340 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1e350 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1e360 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1e370 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1e380 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1e390 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1e3a0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1e3b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1e3c0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1e3d0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1e3e0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1e3f0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1e400 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1e410 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1e420 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1e430 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1e440 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1e450 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e460 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1e470 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1e480 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1e490 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1e4a0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1e4b0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1e4c0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1e4d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1e4e0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
1e4f0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1e500 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
1e510 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
1e520 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
1e530 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
1e540 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
1e550 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
1e560 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
1e570 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
1e580 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
1e590 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
1e5a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  /.SQLITE_API cha
1e5b0 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1e5c0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1e5d0 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1e5e0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1e5f0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1e600 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51  r*, va_list);.SQ
1e610 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1e620 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1e630 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1e640 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
1e650 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1e660 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1e670 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1e680 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1e690 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e6a0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1e6b0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1e6c0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1e6d0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1e6e0 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1e6f0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1e700 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1e710 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1e720 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1e730 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1e740 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1e750 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1e760 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1e770 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1e780 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1e790 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1e7a0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1e7b0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1e7c0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1e7d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e7e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1e7f0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1e800 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1e810 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1e820 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1e830 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1e840 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1e850 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1e860 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1e870 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1e880 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1e890 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1e8a0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1e8b0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1e8c0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1e8d0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1e8e0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1e8f0 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1e900 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1e910 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1e920 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
1e930 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
1e940 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
1e950 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
1e960 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1e970 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1e980 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1e990 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
1e9a0 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
1e9b0 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
1e9c0 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
1e9d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
1e9e0 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
1e9f0 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
1ea00 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
1ea10 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
1ea20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
1ea30 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1ea40 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
1ea50 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
1ea60 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
1ea70 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
1ea80 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
1ea90 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
1eaa0 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
1eab0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
1eac0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
1ead0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
1eae0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1eaf0 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
1eb00 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
1eb10 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1eb20 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
1eb30 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
1eb40 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
1eb50 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
1eb60 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
1eb70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
1eb80 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
1eb90 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1eba0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1ebb0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ebc0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1ebd0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1ebe0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1ebf0 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1ec00 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1ec10 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1ec20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1ec30 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1ec40 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1ec50 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
1ec60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
1ec70 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
1ec80 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1ec90 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
1eca0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1ecb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1ecc0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
1ecd0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1ece0 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
1ecf0 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
1ed00 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1ed10 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
1ed20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
1ed30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1ed40 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1ed50 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
1ed60 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1ed70 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ed80 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1ed90 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1eda0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1edb0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1edc0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1edd0 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
1ede0 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
1edf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1ee00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1ee10 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1ee20 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
1ee30 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1ee40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1ee50 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1ee60 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1ee70 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
1ee80 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
1ee90 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
1eea0 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1eeb0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1eec0 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1eed0 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1eee0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1eef0 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1ef00 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1ef10 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1ef20 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1ef30 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ef40 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1ef50 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1ef60 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1ef70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1ef80 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
1ef90 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1efa0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
1efb0 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
1efc0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1efd0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1efe0 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
1eff0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
1f000 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
1f010 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
1f020 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
1f030 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
1f040 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
1f050 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
1f060 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
1f070 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
1f080 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
1f090 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
1f0a0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
1f0b0 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
1f0c0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
1f0d0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
1f0e0 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
1f0f0 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
1f100 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
1f110 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
1f120 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
1f130 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
1f140 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
1f150 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
1f160 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
1f170 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
1f180 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1f190 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
1f1a0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
1f1b0 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
1f1c0 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
1f1d0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
1f1e0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
1f1f0 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
1f200 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1f210 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
1f220 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
1f230 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
1f240 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
1f250 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
1f260 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
1f270 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
1f280 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
1f290 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
1f2a0 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
1f2b0 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
1f2c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
1f2d0 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
1f2e0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
1f2f0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
1f300 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
1f310 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
1f320 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
1f330 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
1f340 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
1f350 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
1f360 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
1f370 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
1f380 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1f390 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
1f3a0 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
1f3b0 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
1f3c0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
1f3d0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
1f3e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1f3f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1f400 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
1f410 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
1f420 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
1f430 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1f440 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
1f450 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
1f460 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
1f470 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
1f480 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
1f490 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
1f4a0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
1f4b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1f4c0 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  c()]..*/.SQLITE_
1f4d0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
1f4e0 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53  3_malloc(int);.S
1f4f0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1f500 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f510 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  void*, int);.SQL
1f520 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1f530 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1f540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f550 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1f560 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1f570 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1f580 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1f590 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1f5a0 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1f5b0 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1f5c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1f5d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1f5e0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1f5f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1f600 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1f610 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1f620 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1f630 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1f640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1f650 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1f660 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1f670 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1f680 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1f690 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1f6a0 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1f6b0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1f6c0 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1f6d0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1f6e0 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1f6f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1f700 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1f710 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1f720 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1f730 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1f740 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1f750 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1f760 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1f770 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1f780 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1f790 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1f7a0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1f7b0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1f7c0 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1f7d0 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1f7e0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1f7f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1f800 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1f810 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1f820 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1f830 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1f840 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1f850 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1f860 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1f870 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1f880 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1f890 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1f8a0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1f8b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1f8c0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1f8d0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1f8e0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1f8f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1f900 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1f910 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1f920 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1f930 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1f940 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1f950 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1f960 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1f970 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51  the reset..*/.SQ
1f980 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
1f990 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1f9a0 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1f9b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
1f9c0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1f9d0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1f9e0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1f9f0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1fa00 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1fa10 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1fa20 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1fa30 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1fa40 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1fa50 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1fa60 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1fa70 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1fa80 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1fa90 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1faa0 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1fab0 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1fac0 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1fad0 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1fae0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1faf0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1fb00 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1fb10 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1fb20 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1fb30 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1fb40 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1fb50 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1fb60 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1fb70 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1fb80 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1fb90 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1fba0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1fbb0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1fbc0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1fbd0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1fbe0 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r P..**.** ^The 
1fbf0 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
1fc00 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
1fc10 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
1fc20 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
1fc30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
1fc40 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
1fc50 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1fc60 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
1fc70 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
1fc80 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
1fc90 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1fca0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1fcb0 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73  .** ^On all subs
1fcc0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
1fcd0 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72  ns, the pseudo-r
1fce0 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
1fcf0 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
1fd00 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
1fd10 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
1fd20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
1fd30 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
1fd40 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  thod..*/.SQLITE_
1fd50 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
1fd60 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
1fd70 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
1fd80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1fd90 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
1fda0 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
1fdb0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ks.**.** ^This r
1fdc0 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
1fdd0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
1fde0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
1fdf0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1fe00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1fe10 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
1fe20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1fe30 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
1fe40 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1fe50 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
1fe60 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
1fe70 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
1fe80 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
1fe90 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1fea0 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
1feb0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1fec0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
1fed0 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
1fee0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1fef0 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v2()].  ^At va
1ff00 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
1ff10 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
1ff20 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
1ff30 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
1ff40 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
1ff50 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
1ff60 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
1ff70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ff80 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
1ff90 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
1ffa0 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
1ffb0 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
1ffc0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
1ffd0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
1ffe0 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
1fff0 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
20000 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
20010 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
20020 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
20030 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
20040 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
20050 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
20060 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
20070 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
20080 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
20090 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
200a0 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
200b0 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
200c0 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
200d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
200e0 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
200f0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
20100 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
20110 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
20120 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
20130 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
20140 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20150 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
20160 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
20170 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
20180 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
20190 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
201a0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
201b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
201c0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
201d0 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
201e0 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
201f0 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
20200 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
20210 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
20220 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
20230 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
20240 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
20250 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
20260 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
20270 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
20280 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
20290 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
202a0 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
202b0 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
202c0 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
202d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
202e0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
202f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
20300 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
20310 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
20320 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
20330 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
20340 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
20350 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
20360 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
20370 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
20380 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
20390 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
203a0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
203b0 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
203c0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
203d0 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
203e0 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
203f0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
20400 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
20410 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
20420 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
20430 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
20440 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
20450 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
20460 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
20470 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
20480 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
20490 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
204a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
204b0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
204c0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
204d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
204e0 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
204f0 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
20500 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
20510 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
20520 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
20530 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
20540 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
20550 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
20560 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
20570 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
20580 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
20590 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
205a0 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
205b0 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
205c0 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
205d0 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
205e0 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66   a table..** ^If
205f0 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
20600 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
20610 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
20620 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
20630 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
20640 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
20650 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
20660 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
20670 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
20680 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
20690 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
206a0 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
206b0 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
206c0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
206d0 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
206e0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
206f0 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
20700 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
20710 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
20720 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
20730 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
20740 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
20750 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
20760 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
20770 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
20780 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
20790 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
207a0 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
207b0 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
207c0 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
207d0 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
207e0 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
207f0 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
20800 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
20810 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
20820 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
20830 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
20840 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
20850 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
20860 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
20870 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
20880 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
20890 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
208a0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
208b0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
208c0 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
208d0 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
208e0 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
208f0 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
20900 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20910 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
20920 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
20930 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
20940 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
20950 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
20960 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
20970 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
20980 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
20990 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
209a0 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
209b0 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
209c0 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
209d0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
209e0 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
209f0 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
20a00 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
20a10 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
20a20 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
20a30 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
20a40 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
20a50 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
20a60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
20a70 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
20a80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20a90 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
20aa0 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
20ab0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
20ac0 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
20ad0 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
20ae0 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
20af0 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
20b00 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
20b10 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
20b20 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
20b30 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
20b40 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
20b50 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
20b60 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
20b70 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
20b80 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
20b90 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
20ba0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
20bb0 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
20bc0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
20bd0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
20be0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20bf0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
20c00 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
20c10 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
20c20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20c30 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
20c40 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
20c50 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
20c60 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
20c70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20c80 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
20c90 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
20ca0 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
20cb0 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
20cc0 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
20cd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
20ce0 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
20cf0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
20d00 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
20d10 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
20d20 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
20d30 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
20d40 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
20d50 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
20d60 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
20d70 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
20d80 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
20d90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20da0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
20db0 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
20dc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
20dd0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
20de0 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
20df0 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
20e00 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
20e10 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
20e20 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
20e30 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
20e40 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
20e50 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
20e60 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
20e70 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
20e80 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
20e90 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
20ea0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
20eb0 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
20ec0 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ange..*/.SQLITE_
20ed0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
20ee0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
20ef0 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
20f00 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
20f10 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
20f20 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
20f30 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
20f40 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
20f50 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
20f60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
20f70 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
20f80 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
20f90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
20fa0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
20fb0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
20fc0 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
20fd0 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
20fe0 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
20ff0 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
21000 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
21010 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
21020 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
21030 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
21040 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
21050 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
21060 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
21070 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
21080 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
21090 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
210a0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
210b0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
210c0 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
210d0 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49   used as a [SQLI
210e0 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65  TE_ROLLBACK | re
210f0 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72  turn code].** fr
21100 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
21110 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
21120 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
21130 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21140 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
21150 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
21160 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
21170 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
21180 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
21190 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
211a0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
211b0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
211c0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
211d0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
211e0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
211f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
21200 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21210 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
21220 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
21230 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
21240 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
21250 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
21260 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
21270 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
21280 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
21290 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
212a0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
212b0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
212c0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
212d0 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
212e0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
212f0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
21300 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
21310 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
21320 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21330 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
21340 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
21350 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
21360 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
21370 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
21380 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
21390 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
213a0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
213b0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
213c0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
213d0 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
213e0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
213f0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
21400 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
21410 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
21420 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
21430 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
21440 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
21450 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
21460 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
21470 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
21480 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
21490 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
214a0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
214b0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
214c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
214d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
214e0 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
214f0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
21500 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
21510 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
21520 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
21530 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
21540 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
21550 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
21560 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
21570 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
21580 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
21590 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
215a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
215b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
215c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
215d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
215e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
215f0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
21600 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
21610 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
21620 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21630 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21640 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
21650 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
21660 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21670 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21680 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21690 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
216a0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
216b0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
216c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
216d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
216e0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
216f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21700 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21710 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21720 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21730 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
21740 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
21750 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
21760 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21770 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
21780 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
21790 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
217a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
217b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
217c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
217d0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
217e0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
217f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21800 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21810 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
21820 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
21830 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
21840 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21850 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21860 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
21870 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
21880 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21890 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
218a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
218b0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
218c0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
218d0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
218e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
218f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21900 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
21910 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
21920 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
21930 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21940 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21950 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
21960 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
21970 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
21980 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
219a0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
219b0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
219c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
219d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
219e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
219f0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
21a00 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
21a10 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
21a20 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21a30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
21a40 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
21a50 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
21a60 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
21a70 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21a80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21a90 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
21aa0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
21ab0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
21ac0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21ad0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21ae0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
21af0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
21b00 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
21b10 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21b20 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
21b30 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
21b40 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
21b50 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21b60 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21b70 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
21b80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
21b90 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
21ba0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
21bb0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
21bc0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
21bd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
21be0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21bf0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
21c00 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
21c10 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
21c20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
21c30 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
21c40 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21c50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21c60 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
21c70 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
21c80 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
21c90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21ca0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21cb0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
21cc0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
21cd0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21ce0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
21cf0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21d00 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
21d10 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
21d20 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
21d30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21d40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21d50 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
21d60 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
21d70 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
21d80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21d90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21da0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
21db0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
21dc0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
21dd0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21de0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21df0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
21e00 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
21e10 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
21e20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21e30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21e40 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
21e50 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
21e60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21e70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21e80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21e90 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
21ea0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
21eb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
21ec0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
21ed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21ee0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
21ef0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
21f00 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
21f10 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
21f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
21f30 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
21f40 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
21f50 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
21f60 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
21f70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
21f80 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
21f90 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
21fa0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
21fb0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
21fc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
21fd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21fe0 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
21ff0 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
22000 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
22010 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
22020 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
22030 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
22040 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
22050 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
22060 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
22070 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
22080 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
22090 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
220a0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
220b0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
220c0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
220d0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
220e0 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
220f0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
22100 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
22110 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
22120 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
22130 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
22140 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
22150 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
22160 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
22170 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
22180 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
22190 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
221a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
221b0 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
221c0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
221d0 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
221e0 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
221f0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
22200 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
22210 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
22220 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
22230 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
22240 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
22250 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
22260 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
22270 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
22280 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )^.**.** ^The ca
22290 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
222a0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
222b0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
222c0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
222d0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
222e0 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
222f0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
22300 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
22310 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
22320 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
22330 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
22340 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
22350 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
22360 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
22370 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
22380 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
22390 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
223a0 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
223b0 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
223c0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
223d0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
223e0 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
223f0 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
22400 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
22410 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
22420 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
22430 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
22440 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
22450 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
22460 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
22470 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
22480 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
22490 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
224a0 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
224b0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
224c0 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
224d0 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
224e0 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
224f0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
22500 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
22510 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
22520 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
22530 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
22540 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
22550 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
22560 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
22570 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
22580 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
22590 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
225a0 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
225b0 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
225c0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
225d0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
225e0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
225f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
22600 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
22610 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
22620 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
22630 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
22640 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
22650 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
22660 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
22670 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
22680 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
22690 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
226a0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
226b0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
226c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
226d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
226e0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
226f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22700 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
22710 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
22720 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
22730 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
22740 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
22750 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
22760 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
22770 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
22780 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
22790 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
227a0 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
227b0 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
227c0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
227d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  the number of .*
227e0 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
227f0 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
22800 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
22810 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
22820 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
22830 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
22840 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e  lback X..**.** ^
22850 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
22860 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
22870 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
22880 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
22890 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
228a0 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
228b0 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
228c0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
228d0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
228e0 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
228f0 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
22900 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
22910 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
22920 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
22930 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
22940 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
22950 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
22960 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
22970 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
22980 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
22990 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
229a0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
229b0 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
229c0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
229d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
229e0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
229f0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
22a00 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
22a10 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
22a20 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
22a30 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
22a40 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
22a50 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
22a60 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
22a70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22a80 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
22a90 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
22aa0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
22ab0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22ac0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
22ad0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
22ae0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
22af0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22b00 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
22b10 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
22b20 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
22b30 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54  aph..**.*/.SQLIT
22b40 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
22b50 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
22b60 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
22b70 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
22b80 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
22b90 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
22ba0 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
22bb0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
22bc0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
22bd0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
22be0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
22bf0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
22c00 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
22c10 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
22c20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
22c30 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
22c40 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
22c50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
22c60 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
22c70 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
22c80 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
22c90 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
22ca0 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
22cb0 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
22cc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
22cd0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
22ce0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
22cf0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
22d00 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
22d10 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
22d20 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
22d30 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
22d40 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
22d50 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
22d60 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
22d70 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
22d80 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
22d90 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
22da0 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
22db0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
22dc0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
22dd0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
22de0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
22df0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
22e00 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
22e10 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
22e20 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
22e30 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
22e40 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
22e50 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
22e60 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
22e70 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
22e80 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
22e90 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
22ea0 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
22eb0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
22ec0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
22ed0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
22ee0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
22ef0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
22f00 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
22f10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
22f20 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
22f30 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
22f40 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
22f50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
22f60 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
22f70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
22f80 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
22f90 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
22fa0 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
22fb0 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
22fc0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
22fd0 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
22fe0 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
22ff0 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
23000 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
23010 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
23020 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23030 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
23040 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
23050 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
23060 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
23070 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
23080 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
23090 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
230a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
230b0 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
230c0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
230d0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
230e0 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
230f0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
23100 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
23110 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
23120 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
23130 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23140 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
23150 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
23160 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23170 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
23180 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
23190 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
231a0 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
231b0 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
231c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
231d0 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
231e0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
231f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
23200 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
23210 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
23220 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
23230 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
23240 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
23250 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
23260 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
23270 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
23280 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
23290 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
232a0 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
232b0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
232c0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
232d0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
232e0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
232f0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
23300 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
23310 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
23320 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
23330 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
23340 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
23350 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
23360 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
23370 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
23380 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
23390 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
233a0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
233b0 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
233c0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
233d0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
233e0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
233f0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
23400 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
23410 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
23420 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
23430 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
23440 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
23450 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
23460 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
23470 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
23480 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
23490 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
234a0 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
234b0 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
234c0 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
234d0 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
234e0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
234f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
23500 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
23510 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
23520 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
23530 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
23540 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
23550 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
23560 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
23570 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
23580 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
23590 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
235a0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
235b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
235c0 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
235d0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
235e0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
235f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
23600 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
23610 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
23620 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23630 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
23640 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
23650 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
23660 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
23670 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
23680 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
23690 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
236a0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
236b0 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
236c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
236d0 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
236e0 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
236f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23700 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
23710 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
23720 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
23730 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
23740 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
23750 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
23760 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
23770 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
23780 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
23790 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
237a0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
237b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
237c0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
237d0 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
237e0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
237f0 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
23800 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
23810 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
23820 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
23830 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
23840 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
23850 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
23860 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
23870 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
23880 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
23890 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
238a0 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
238b0 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
238c0 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
238d0 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
238e0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
238f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
23900 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
23910 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
23920 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
23930 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
23940 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
23950 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
23960 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
23970 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
23980 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
23990 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
239a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
239b0 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
239c0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
239d0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
239e0 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
239f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
23a00 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
23a10 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
23a20 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
23a30 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
23a40 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
23a50 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
23a60 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
23a70 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
23a80 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
23a90 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
23aa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
23ab0 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
23ac0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
23ad0 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
23ae0 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
23af0 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
23b00 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
23b10 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
23b20 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
23b30 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
23b40 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
23b50 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
23b60 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
23b70 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
23b80 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
23b90 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
23ba0 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
23bb0 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
23bc0 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
23bd0 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
23be0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
23bf0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
23c00 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
23c10 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
23c20 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
23c30 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
23c40 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
23c50 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
23c60 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
23c70 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
23c80 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
23c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23ca0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
23cb0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
23cc0 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
23cd0 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
23ce0 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
23cf0 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
23d00 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
23d10 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
23d20 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
23d30 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
23d40 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
23d50 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
23d60 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
23d70 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
23d80 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
23d90 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
23da0 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
23db0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
23dc0 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
23dd0 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
23de0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
23df0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
23e00 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
23e10 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
23e20 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
23e30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
23e40 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
23e50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
23e60 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
23e70 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
23e80 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
23e90 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
23ea0 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
23eb0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
23ec0 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
23ed0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
23ee0 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
23ef0 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
23f00 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
23f10 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
23f20 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
23f30 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
23f40 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
23f50 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
23f60 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
23f70 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
23f80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
23f90 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
23fa0 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
23fb0 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
23fc0 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
23fd0 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
23fe0 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
23ff0 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
24000 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
24010 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
24020 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
24030 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
24040 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
24050 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
24060 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
24070 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
24080 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
24090 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
240a0 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
240b0 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
240c0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
240d0 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
240e0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
240f0 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
24100 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
24110 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
24120 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
24130 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
24140 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
24150 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
24160 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
24170 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
24180 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
24190 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
241a0 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
241b0 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
241c0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
241d0 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
241e0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
241f0 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
24200 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
24210 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
24220 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e  ve path. .** ^On
24230 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
24240 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
24250 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
24260 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
24270 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
24280 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a  e.g. "C:")..**.*
24290 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
242a0 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
242b0 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
242c0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
242d0 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
242e0 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
242f0 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
24300 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
24310 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
24320 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
24330 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
24340 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  ]..** SQLite int
24350 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c  erprets the foll
24360 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72  owing three quer
24370 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
24380 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
24390 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
243a0 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
243b0 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
243c0 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
243d0 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
243e0 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
243f0 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
24400 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
24410 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
24420 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
24430 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
24440 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
24450 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
24460 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
24470 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
24480 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
24490 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
244a0 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
244b0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
244c0 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
244d0 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
244e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
244f0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
24500 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
24510 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
24520 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
24530 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
24540 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
24550 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
24560 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
24570 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
24580 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
24590 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
245a0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
245b0 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
245c0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
245d0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
245e0 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
245f0 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
24600 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
24610 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
24620 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
24630 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
24640 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
24650 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
24660 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
24670 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24680 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
24690 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
246a0 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
246b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
246c0 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
246d0 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
246e0 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
246f0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
24700 70 72 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49  prepare_v2(). ^I
24710 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
24720 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
24730 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
24740 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24750 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
24760 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
24770 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
24780 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
24790 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
247a0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
247b0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
247c0 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
247d0 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
247e0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
247f0 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
24800 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
24810 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
24820 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
24830 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
24840 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
24850 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
24860 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
24870 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
24880 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
24890 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
248a0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
248b0 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
248c0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
248d0 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
248e0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
248f0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
24900 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
24910 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
24920 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
24930 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
24940 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
24950 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
24960 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
24970 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
24980 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
24990 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
249a0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
249b0 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
249c0 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
249d0 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
249e0 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
249f0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
24a00 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
24a10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
24a20 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
24a30 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
24a40 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
24a50 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
24a60 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
24a70 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
24a80 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
24a90 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
24aa0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
24ab0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
24ac0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
24ad0 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
24ae0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24af0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
24b00 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
24b10 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
24b20 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
24b30 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
24b40 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
24b50 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 73 74  ehaviour request
24b60 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
24b70 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
24b80 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
24b90 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
24ba0 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
24bb0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
24bc0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
24bd0 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
24be0 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
24bf0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
24c00 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
24c10 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
24c20 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
24c30 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
24c40 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
24c50 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
24c60 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
24c70 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
24c80 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
24c90 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
24ca0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
24cb0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
24cc0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
24cd0 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
24ce0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
24cf0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
24d00 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
24d10 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
24d20 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
24d30 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
24d40 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
24d50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
24d60 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
24d70 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
24d80 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
24d90 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
24da0 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
24db0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
24dc0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
24dd0 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
24de0 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
24df0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
24e00 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
24e10 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
24e20 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
24e30 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
24e40 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
24e50 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
24e60 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24e70 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
24e80 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
24e90 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24ea0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
24eb0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
24ec0 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
24ed0 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
24ee0 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
24ef0 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
24f00 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
24f10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
24f20 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
24f30 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
24f40 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
24f50 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
24f60 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
24f70 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
24f80 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
24f90 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
24fa0 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
24fb0 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
24fc0 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
24fd0 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
24fe0 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
24ff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
25000 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
25010 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
25020 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
25030 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
25040 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
25050 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
25060 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
25070 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
25080 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
25090 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
250a0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
250b0 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
250c0 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
250d0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
250e0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
250f0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
25100 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
25110 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
25120 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
25130 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
25140 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
25150 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
25160 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
25170 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a  x-nolock <td>.**
25180 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
25190 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
251a0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
251b0 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
251c0 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20  nix-nolock"..** 
251d0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
251e0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
251f0 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
25200 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
25210 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
25220 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
25230 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
25240 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
25250 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
25260 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
25270 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
25280 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
25290 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
252a0 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
252b0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
252c0 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
252d0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
252e0 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
252f0 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
25300 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
25310 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
25320 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
25330 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
25340 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
25350 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
25360 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
25370 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
25380 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
25390 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
253a0 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
253b0 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
253c0 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
253d0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
253e0 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
253f0 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
25400 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
25410 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
25420 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
25430 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
25440 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
25450 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
25460 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
25470 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
25480 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
25490 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
254a0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
254b0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
254c0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
254d0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
254e0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
254f0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
25500 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
25510 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
25520 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
25530 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
25540 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
25550 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
25560 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
25570 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
25580 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
25590 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
255a0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
255b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
255c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
255d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
255e0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
255f0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
25600 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
25610 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
25620 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
25630 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
25640 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
25650 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
25660 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
25670 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
25680 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
25690 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
256a0 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
256b0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
256c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
256d0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
256e0 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
256f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
25700 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
25710 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
25720 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
25730 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
25740 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
25750 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
25760 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
25770 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
25780 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
25790 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
257a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
257b0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
257c0 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
257d0 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
257e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
257f0 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
25800 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
25810 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69  ** These are uti
25820 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75  lity routines, u
25830 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70  seful to VFS imp
25840 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68  lementations, th
25850 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73  at check.** to s
25860 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
25870 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
25880 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
25890 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
258a0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
258b0 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
258c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
258d0 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  at query paramet
258e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69  er..**.** If F i
258f0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
25900 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  ilename pointer 
25910 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
25920 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f  xOpen() method o
25930 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c  f .** a VFS impl
25940 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20  ementation when 
25950 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
25960 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68  ter to xOpen() h
25970 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f  as one or .** mo
25980 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
25990 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b  E_OPEN_URI] or [
259a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
259b0 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e  _DB] bits set an
259c0 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61  d.** P is the na
259d0 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  me of the query 
259e0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a  parameter, then.
259f0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  ** sqlite3_uri_p
25a00 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
25a10 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
25a20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61  of the P.** para
25a30 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73  meter if it exis
25a40 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ts or a NULL poi
25a50 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e  nter if P does n
25a60 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a  ot appear as a .
25a70 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
25a80 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69  er on F.  If P i
25a90 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  s a query parame
25aa0 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20  ter of F.** has 
25ab0 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75  no explicit valu
25ac0 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
25ad0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
25ae0 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  P) returns.** a 
25af0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d  pointer to an em
25b00 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
25b10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
25b20 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
25b30 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73   routine assumes
25b40 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f   that P is a boo
25b50 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65  lean.** paramete
25b60 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72  r and returns tr
25b70 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20  ue (1) or false 
25b80 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  (0) according to
25b90 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66   the value.** of
25ba0 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33   P.  The sqlite3
25bb0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
25bc0 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,B) routine retu
25bd0 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20  rns true (1) if 
25be0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
25bf0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
25c00 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73  P is one of "yes
25c10 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f  ", "true", or "o
25c20 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73  n" in any.** cas
25c30 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  e or if the valu
25c40 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
25c50 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e  non-zero number.
25c60 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65    The .** sqlite
25c70 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
25c80 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65  P,B) routines re
25c90 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20  turns false (0) 
25ca0 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  if the value of.
25cb0 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
25cc0 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
25cd0 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72  no", "false", or
25ce0 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61   "off" in any ca
25cf0 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20  se or.** if the 
25d00 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
25d10 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f  h a numeric zero
25d20 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61  .  If P is not a
25d30 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
25d40 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74  ter on F or if t
25d50 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
25d60 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
25d70 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62  any of the.** ab
25d80 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ove, then sqlite
25d90 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
25da0 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21  P,B) returns (B!
25db0 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  =0)..**.** The s
25dc0 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
25dd0 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20  (F,P,D) routine 
25de0 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c  converts the val
25df0 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a  ue of P into a.*
25e00 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  * 64-bit signed 
25e10 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75  integer and retu
25e20 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72  rns that integer
25e30 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73  , or D if P does
25e40 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20   not.** exist.  
25e50 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  If the value of 
25e60 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f  P is something o
25e70 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74  ther than an int
25e80 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65  eger, then.** ze
25e90 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
25ea0 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61  ** .** If F is a
25eb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
25ec0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
25ed0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
25ee0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a  eturns NULL and.
25ef0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
25f00 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
25f10 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69  turns B.  If F i
25f20 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69  s not a NULL poi
25f30 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e  nter and.** is n
25f40 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
25f50 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e  le pathname poin
25f60 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  ter that SQLite 
25f70 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
25f80 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74  xOpen.** VFS met
25f90 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  hod, then the be
25fa0 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72  havior of this r
25fb0 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69  outine is undefi
25fc0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
25fd0 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  .** undesirable.
25fe0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
25ff0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
26000 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
26010 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
26020 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
26030 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c  ar *zParam);.SQL
26040 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
26050 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
26060 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
26070 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
26080 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
26090 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ult);.SQLITE_API
260a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
260b0 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
260c0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
260d0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
260e0 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
260f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
26100 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
26110 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sages.**.** ^The
26120 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
26130 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
26140 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
26150 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
26160 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
26170 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
26180 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
26190 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
261a0 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73   API call.** ass
261b0 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
261c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
261d0 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72  ion]. If a prior
261e0 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
261f0 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74  .** but the most
26200 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
26210 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
26220 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
26230 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72  m.** sqlite3_err
26240 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
26250 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ned.  ^The sqlit
26260 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
26270 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
26280 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
26290 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
262a0 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
262b0 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
262c0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
262d0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
262e0 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
262f0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
26300 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26310 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
26320 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
26330 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
26340 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
26350 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
26360 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
26370 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
26380 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
26390 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
263a0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
263b0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
263c0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
263d0 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
263e0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
263f0 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
26400 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
26410 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
26420 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
26430 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
26440 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
26450 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
26460 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
26470 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
26480 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
26490 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57  tions.)^.**.** W
264a0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
264b0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
264c0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
264d0 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
264e0 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
264f0 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
26500 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
26510 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
26520 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
26530 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
26540 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
26550 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
26560 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
26570 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
26580 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
26590 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
265a0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
265b0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
265c0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
265d0 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
265e0 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
265f0 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
26600 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
26610 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
26620 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26630 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
26640 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
26650 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
26660 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
26670 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
26680 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
26690 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
266a0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
266b0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
266c0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
266d0 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
266e0 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
266f0 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
26700 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
26710 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
26720 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
26730 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
26740 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
26750 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
26760 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
26770 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
26780 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
26790 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
267a0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
267b0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
267c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
267d0 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
267e0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
267f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
26800 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
26810 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
26820 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
26830 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
26840 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
26850 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
26860 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
26870 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
26880 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
26890 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
268a0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
268b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
268c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
268d0 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
268e0 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
268f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
26900 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
26910 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
26920 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
26930 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
26940 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
26950 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
26960 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
26970 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
26980 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
26990 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
269a0 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
269b0 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
269c0 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
269d0 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
269e0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
269f0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
26a00 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
26a10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26a20 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
26a30 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
26a40 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
26a50 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
26a60 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
26a70 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
26a80 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
26a90 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
26aa0 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
26ab0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
26ac0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
26ad0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
26ae0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
26af0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
26b00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
26b10 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
26b20 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
26b30 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
26b40 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
26b50 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
26b60 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
26b70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
26b80 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
26b90 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
26ba0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
26bb0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
26bc0 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
26bd0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
26be0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
26bf0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
26c00 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
26c10 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
26c20 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
26c30 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28   Limits.**.** ^(
26c40 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
26c50 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
26c60 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
26c70 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
26c80 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
26c90 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
26ca0 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
26cb0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
26cc0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
26cd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26ce0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
26cf0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
26d00 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
26d10 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
26d20 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
26d30 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
26d40 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
26d50 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
26d60 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
26d70 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
26d80 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
26d90 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
26da0 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
26db0 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
26dc0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
26dd0 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
26de0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
26df0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
26e00 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
26e10 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
26e20 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
26e30 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
26e40 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
26e50 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
26e60 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
26e70 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
26e80 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
26e90 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
26ea0 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
26eb0 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
26ec0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
26ed0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
26ee0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
26ef0 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
26f00 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
26f10 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
26f20 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
26f30 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
26f40 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
26f50 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
26f60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
26f70 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
26f80 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
26f90 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
26fa0 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
26fb0 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
26fc0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
26fd0 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
26fe0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
26ff0 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
27000 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
27010 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
27020 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
27030 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
27040 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
27050 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
27060 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
27070 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
27080 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
27090 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
270a0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
270b0 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
270c0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
270d0 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
270e0 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
270f0 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
27100 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
27110 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
27120 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
27130 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
27140 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
27150 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
27160 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
27170 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
27180 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
27190 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
271a0 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
271b0 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
271c0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
271d0 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
271e0 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
271f0 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
27200 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
27210 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
27220 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
27230 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
27240 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
27250 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
27260 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
27270 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
27280 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
27290 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
272a0 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
272b0 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
272c0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
272d0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
272e0 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
272f0 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
27300 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
27310 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
27320 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
27330 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
27340 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
27350 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
27360 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
27370 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
27380 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
27390 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
273a0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
273b0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
273c0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
273d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
273e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
273f0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
27400 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
27410 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27420 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
27430 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
27440 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
27450 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
27460 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
27470 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
27480 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
27490 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
274a0 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
274b0 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
274c0 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
274d0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
274e0 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
274f0 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
27500 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
27510 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
27520 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
27530 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
27540 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
27550 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
27560 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
27570 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
27580 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
27590 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
275a0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
275b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
275c0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
275d0 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
275e0 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
275f0 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
27600 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
27610 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
27620 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27630 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
27640 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27650 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
27660 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
27670 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
27680 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
27690 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
276a0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
276b0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
276c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
276d0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
276e0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
276f0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
27700 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
27710 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
27720 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
27730 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
27740 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
27750 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
27760 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
27770 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
27780 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
27790 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
277a0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
277b0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
277c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
277d0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
277e0 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
277f0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
27800 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
27810 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
27820 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
27830 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
27840 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
27850 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
27860 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
27870 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
27880 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
27890 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
278a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
278b0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
278c0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
278d0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
278e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
278f0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
27900 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
27910 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
27920 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
27930 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
27940 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
27950 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e   This limit is n
27960 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  ot currently.** 
27970 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68  enforced, though
27980 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61   that might be a
27990 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74  dded in some fut
279a0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
279b0 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e  * SQLite.</dd>)^
279c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
279d0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
279e0 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  RG]] ^(<dt>SQLIT
279f0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
27a00 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
27a10 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
27a20 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
27a30 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
27a40 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
27a50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
27a60 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  CHED]] ^(<dt>SQL
27a70 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
27a80 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
27a90 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
27aa0 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
27ab0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
27ac0 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
27ad0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
27ae0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
27af0 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  GTH]].** ^(<dt>S
27b00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
27b10 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
27b20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27b30 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
27b40 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
27b50 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
27b60 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
27b70 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
27b80 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
27b90 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
27ba0 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28  E_NUMBER]].** ^(
27bb0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
27bc0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
27bd0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27be0 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e   maximum index n
27bf0 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61  umber of any [pa
27c00 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53  rameter] in an S
27c10 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a  QL statement.)^.
27c20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
27c30 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
27c40 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
27c50 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
27c60 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
27c70 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
27c80 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
27c90 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
27ca0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
27cb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
27cc0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
27cd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27ce0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
27cf0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
27d00 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
27d10 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
27d20 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
27d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27d40 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
27d50 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
27d60 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
27d70 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
27d80 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
27d90 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
27da0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
27db0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
27dc0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
27dd0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
27de0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
27df0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
27e00 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
27e10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
27e20 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
27e30 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
27e40 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
27e50 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
27e60 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
27e70 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
27e80 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
27e90 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
27ea0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27eb0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
27ec0 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a            10../*
27ed0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
27ee0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
27ef0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
27f00 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
27f10 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
27f20 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
27f30 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
27f40 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
27f50 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
27f60 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
27f70 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
27f80 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
27f90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
27fa0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
27fb0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
27fc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
27fd0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
27fe0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
27ff0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
28000 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
28010 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
28020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
28030 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
28040 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28050 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
28060 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
28070 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
28080 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
28090 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
280a0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
280b0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
280c0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
280d0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
280e0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
280f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
28100 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
28110 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
28120 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
28130 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
28140 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
28150 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
28160 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
28170 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
28180 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
28190 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
281a0 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
281b0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
281c0 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
281d0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
281e0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
281f0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
28200 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
28210 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
28220 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
28230 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
28240 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
28250 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
28260 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
28270 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
28280 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
28290 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
282a0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
282b0 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
282c0 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
282d0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
282e0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
282f0 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
28300 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
28310 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
28320 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
28330 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
28340 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
28350 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
28360 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
28370 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
28380 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
28390 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
283a0 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
283b0 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69  tor bytes as thi
283c0 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66  s saves SQLite f
283d0 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a  rom having to.**
283e0 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
283f0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
28400 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
28410 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
28420 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
28430 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
28440 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
28450 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
28460 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
28470 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
28480 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
28490 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
284a0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
284b0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
284c0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
284d0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
284e0 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
284f0 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
28500 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
28510 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
28520 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
28530 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
28540 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
28550 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
28560 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
28570 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
28580 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
28590 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
285a0 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
285b0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
285c0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
285d0 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
285e0 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
285f0 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
28600 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
28610 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
28620 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
28630 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
28640 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
28650 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
28660 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
28670 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
28680 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
28690 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
286a0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
286b0 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
286c0 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
286d0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
286e0 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
286f0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
28700 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
28710 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
28720 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
28730 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
28740 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28750 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
28760 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
28770 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
28780 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
28790 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
287a0 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
287b0 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
287c0 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
287d0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
287e0 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
287f0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
28800 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
28810 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
28820 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
28830 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
28840 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
28850 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
28860 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
28870 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
28880 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
28890 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
288a0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
288b0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
288c0 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
288d0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
288e0 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
288f0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
28900 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
28910 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
28920 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
28930 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
28940 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
28950 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
28960 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
28970 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
28980 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
28990 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
289a0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
289b0 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a   run it again..*
289c0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
289d0 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
289e0 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
289f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
28a00 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
28a10 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
28a20 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
28a30 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
28a40 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
28a50 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
28a60 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
28a70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
28a80 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
28a90 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
28aa0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
28ab0 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
28ac0 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
28ad0 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
28ae0 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
28af0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28b00 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
28b10 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
28b20 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
28b30 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
28b40 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
28b50 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
28b60 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
28b70 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
28b80 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
28b90 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
28ba0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
28bb0 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
28bc0 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
28bd0 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
28be0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
28bf0 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
28c00 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
28c10 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
28c20 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
28c30 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
28c40 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
28c50 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
28c60 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
28c70 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
28c80 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
28c90 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
28ca0 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
28cb0 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
28cc0 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
28cd0 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
28ce0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
28cf0 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
28d00 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
28d10 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
28d20 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
28d30 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
28d40 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
28d50 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
28d60 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
28d70 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
28d80 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
28d90 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
28da0 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
28db0 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
28dc0 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
28dd0 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
28de0 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
28df0 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
28e00 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
28e10 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
28e20 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
28e30 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68  s enabled..** th
28e40 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  e .** </li>.** <
28e50 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  /ol>.*/.SQLITE_A
28e60 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
28e70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
28e80 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
28e90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
28ea0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28eb0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
28ec0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
28ed0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
28ee0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
28ef0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
28f00 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
28f10 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
28f20 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
28f30 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
28f40 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
28f50 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
28f60 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
28f70 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
28f80 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
28f90 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
28fa0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
28fb0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
28fc0 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
28fd0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
28fe0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
28ff0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
29000 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
29010 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
29020 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
29030 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
29040 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
29050 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
29060 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
29070 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
29080 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
29090 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
290a0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
290b0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
290c0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
290d0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
290e0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
290f0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
29100 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
29110 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
29120 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
29130 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
29140 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
29150 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
29160 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
29170 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
29180 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
29190 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
291a0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
291b0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
291c0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
291d0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
291e0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
291f0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
29200 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
29210 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
29220 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
29230 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
29240 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
29250 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
29260 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
29270 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
29280 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
29290 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
292a0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
292b0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
292c0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
292d0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
292e0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
292f0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
29300 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
29310 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
29320 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
29330 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
29340 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
29350 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
29360 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
29370 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
29380 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
29390 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
293a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
293b0 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
293c0 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
293d0 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
293e0 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
293f0 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
29400 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
29410 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
29420 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
29430 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29440 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
29450 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
29460 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
29470 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
29480 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
29490 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
294a0 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  2()]..*/.SQLITE_
294b0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
294c0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
294d0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
294e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
294f0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
29500 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
29510 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
29520 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  base.**.** ^The 
29530 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
29540 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
29550 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
29560 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
29570 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
29580 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29590 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
295a0 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
295b0 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
295c0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
295d0 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
295e0 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
295f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
29600 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
29610 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
29620 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
29630 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
29640 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
29650 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
29660 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
29670 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
29680 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
29690 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
296a0 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
296b0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
296c0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
296d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
296e0 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
296f0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
29700 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
29710 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
29720 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
29730 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
29740 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
29750 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
29760 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
29770 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
29780 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
29790 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
297a0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
297b0 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
297c0 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
297d0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
297e0 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
297f0 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
29800 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
29810 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
29820 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
29830 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
29840 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
29850 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
29860 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
29870 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
29880 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
29890 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
298a0 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
298b0 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
298c0 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
298d0 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
298e0 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
298f0 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
29900 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
29910 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
29920 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
29930 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
29940 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
29950 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
29960 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
29970 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
29980 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
29990 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
299a0 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
299b0 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
299c0 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
299d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
299e0 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
299f0 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
29a00 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
29a10 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
29a20 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
29a30 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
29a40 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
29a50 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
29a60 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
29a70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
29a80 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
29a90 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
29aa0 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
29ab0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29ac0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
29ad0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29ae0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
29af0 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
29b00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29b10 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
29b20 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
29b30 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
29b40 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
29b50 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f  t has not run to
29b60 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f   completion and/
29b70 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62  or has not .** b
29b80 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
29b90 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
29ba0 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
29bb0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
29bc0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
29bd0 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
29be0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
29bf0 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
29c00 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
29c10 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
29c20 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
29c30 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
29c40 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
29c50 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
29c60 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
29c70 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
29c80 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
29c90 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
29ca0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
29cb0 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
29cc0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
29cd0 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
29ce0 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
29cf0 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
29d00 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
29d10 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
29d20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
29d30 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
29d40 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
29d50 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
29d60 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
29d70 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
29d80 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
29d90 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
29da0 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
29db0 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
29dc0 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  open..*/.SQLITE_
29dd0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29de0 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65  stmt_busy(sqlite
29df0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
29e00 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
29e10 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
29e20 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
29e30 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
29e40 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
29e50 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
29e60 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
29e70 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
29e80 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
29e90 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
29ea0 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
29eb0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
29ec0 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
29ed0 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
29ee0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
29ef0 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
29f00 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
29f10 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
29f20 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
29f30 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
29f40 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
29f50 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
29f60 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
29f70 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
29f80 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
29f90 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
29fa0 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
29fb0 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
29fc0 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
29fd0 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
29fe0 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
29ff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
2a000 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
2a010 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
2a020 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
2a030 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
2a040 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2a050 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
2a060 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
2a070 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
2a080 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
2a090 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
2a0a0 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
2a0b0 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
2a0c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2a0d0 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
2a0e0 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
2a0f0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
2a100 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
2a110 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
2a120 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
2a130 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
2a140 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
2a150 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2a160 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
2a170 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
2a180 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
2a190 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2a1a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
2a1b0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2a1c0 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
2a1d0 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
2a1e0 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
2a1f0 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
2a200 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
2a210 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
2a220 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
2a230 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
2a240 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
2a250 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
2a260 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
2a270 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
2a280 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2a290 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
2a2a0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
2a2b0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
2a2c0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
2a2d0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
2a2e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2a2f0 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
2a300 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
2a310 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
2a320 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
2a330 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
2a340 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
2a350 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
2a360 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
2a370 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
2a380 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2a390 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2a3a0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2a3b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2a3c0 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
2a3d0 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
2a3e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
2a3f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2a400 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
2a410 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
2a420 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
2a430 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2a440 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
2a450 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2a460 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
2a470 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
2a480 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2a490 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2a4a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a4b0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
2a4c0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
2a4d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2a4e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
2a4f0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2a500 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
2a510 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2a520 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2a530 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
2a540 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2a550 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
2a560 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
2a570 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
2a580 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2a590 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a5a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
2a5b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2a5c0 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
2a5d0 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
2a5e0 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
2a5f0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
2a600 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
2a610 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
2a620 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
2a630 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
2a640 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
2a650 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2a660 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
2a670 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
2a680 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
2a690 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
2a6a0 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
2a6b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2a6c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
2a6d0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2a6e0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2a6f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2a700 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
2a710 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
2a720 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
2a730 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2a740 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
2a750 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
2a760 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
2a770 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
2a780 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
2a790 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
2a7a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2a7b0 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
2a7c0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2a7d0 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
2a7e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2a7f0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
2a800 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2a810 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
2a820 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
2a830 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
2a840 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
2a850 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
2a860 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
2a870 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
2a880 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
2a890 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2a8a0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
2a8b0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
2a8c0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
2a8d0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
2a8e0 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e  binding}.**.** ^
2a8f0 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
2a900 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
2a910 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
2a920 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
2a930 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
2a940 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
2a950 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
2a960 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
2a970 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
2a980 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
2a990 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
2a9a0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
2a9b0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
2a9c0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
2a9d0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
2a9e0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
2a9f0 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
2aa00 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
2aa10 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
2aa20 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
2aa30 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
2aa40 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
2aa50 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
2aa60 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
2aa70 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
2aa80 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
2aa90 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
2aaa0 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
2aab0 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
2aac0 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
2aad0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
2aae0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2aaf0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
2ab00 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2ab10 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2ab20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2ab30 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
2ab40 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
2ab50 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2ab60 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
2ab70 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
2ab80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ab90 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
2aba0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
2abb0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2abc0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2abd0 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
2abe0 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
2abf0 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
2ac00 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
2ac10 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
2ac20 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
2ac30 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
2ac40 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
2ac50 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
2ac60 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2ac70 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
2ac80 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
2ac90 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
2aca0 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
2acb0 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
2acc0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
2acd0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
2ace0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
2acf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2ad00 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2ad10 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
2ad20 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
2ad30 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
2ad40 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
2ad50 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
2ad60 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
2ad70 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
2ad80 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
2ad90 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
2ada0 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
2adb0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2adc0 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
2add0 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
2ade0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2adf0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
2ae00 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
2ae10 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
2ae20 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
2ae30 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
2ae40 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
2ae50 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
2ae60 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2ae70 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2ae80 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
2ae90 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
2aea0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2aeb0 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
2aec0 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
2aed0 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
2aee0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2aef0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
2af00 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2af10 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
2af20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
2af30 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
2af40 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
2af50 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
2af60 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2af70 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61  ** If a non-nega
2af80 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61  tive fourth para
2af90 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65  meter is provide
2afa0 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  d to sqlite3_bin
2afb0 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73  d_text().** or s
2afc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2afd0 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20 70  16() then that p
2afe0 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2aff0 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
2b000 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55  .** where the NU
2b010 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
2b020 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e  ld occur assumin
2b030 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72  g the string wer
2b040 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61  e NUL.** termina
2b050 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
2b060 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
2b070 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74  r at byte offset
2b080 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20  s less than .** 
2b090 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2b0a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2b0b0 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  r then the resul
2b0c0 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75  ting string valu
2b0d0 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69  e will.** contai
2b0e0 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e  n embedded NULs.
2b0f0 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20    The result of 
2b100 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f  expressions invo
2b110 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a  lving strings.**
2b120 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
2b130 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
2b140 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
2b150 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2b160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b170 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  (), sqlite3_bind
2b180 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20  _text(), and.** 
2b190 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2b1a0 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72  t16() is a destr
2b1b0 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
2b1c0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2b1d0 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
2b1e0 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
2b1f0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
2b200 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
2b210 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
2b220 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2b230 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
2b240 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
2b250 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  l to sqlite3_bin
2b260 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c  d_blob(),.** sql
2b270 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2b280 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  , or sqlite3_bin
2b290 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73  d_text16() fails
2b2a0 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .  .** ^If the f
2b2b0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
2b2c0 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
2b2d0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
2b2e0 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
2b2f0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
2b300 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
2b310 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
2b320 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
2b330 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
2b340 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
2b350 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
2b360 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
2b370 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
2b380 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
2b390 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
2b3a0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2b3b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
2b3c0 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
2b3d0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
2b3e0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2b3f0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
2b400 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b410 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2b420 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
2b430 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
2b440 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
2b450 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
2b460 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
2b470 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
2b480 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
2b490 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
2b4a0 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
2b4b0 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
2b4c0 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
2b4d0 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
2b4e0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
2b4f0 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
2b500 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
2b510 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
2b520 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
2b530 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2b540 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
2b550 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
2b560 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
2b570 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
2b580 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
2b590 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
2b5a0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2b5b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
2b5c0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
2b5d0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2b5e0 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
2b5f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2b600 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
2b610 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b620 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
2b630 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
2b640 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
2b650 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
2b660 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
2b670 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
2b680 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2b690 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
2b6a0 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
2b6b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2b6c0 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
2b6d0 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
2b6e0 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
2b6f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b700 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
2b710 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
2b720 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
2b730 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2b740 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
2b750 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
2b760 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
2b770 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
2b780 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
2b790 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
2b7a0 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
2b7b0 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
2b7c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b7d0 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
2b7e0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2b7f0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2b800 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
2b810 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
2b820 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
2b830 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
2b840 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2b850 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
2b860 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2b870 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
2b880 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
2b890 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
2b8a0 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
2b8b0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2b8c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2b8d0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
2b8e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2b8f0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2b900 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2b910 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2b920 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2b930 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2b940 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
2b950 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2b960 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
2b970 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2b980 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b990 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
2b9a0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2b9b0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
2b9c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b9d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2b9e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b9f0 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  int, int);.SQLIT
2ba00 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ba10 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
2ba20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2ba30 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2ba40 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ba50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2ba60 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
2ba70 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
2ba80 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2ba90 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
2baa0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2bab0 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20  t char*, int n, 
2bac0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2bad0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2bae0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2baf0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2bb00 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2bb10 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2bb20 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2bb30 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2bb40 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
2bb50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2bb60 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
2bb70 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2bb80 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2bb90 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
2bba0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2bbb0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
2bbc0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2bbd0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
2bbe0 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
2bbf0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
2bc00 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
2bc10 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
2bc20 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
2bc30 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2bc40 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
2bc50 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
2bc60 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
2bc70 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
2bc80 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
2bc90 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
2bca0 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
2bcb0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
2bcc0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
2bcd0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2bce0 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
2bcf0 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
2bd00 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
2bd10 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2bd20 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
2bd30 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
2bd40 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
2bd50 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
2bd60 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
2bd70 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
2bd80 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
2bd90 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
2bda0 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
2bdb0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
2bdc0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2bdd0 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
2bde0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
2bdf0 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
2be00 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
2be10 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2be20 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2be30 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2be40 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2be50 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2be60 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2be70 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2be80 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
2be90 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2bea0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2beb0 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
2bec0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2bed0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2bee0 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
2bef0 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eter.**.** ^The 
2bf00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2bf10 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
2bf20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2bf30 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
2bf40 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
2bf50 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2bf60 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2bf70 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
2bf80 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
2bf90 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
2bfa0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2bfb0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2bfc0 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
2bfd0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
2bfe0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
2bff0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2c000 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
2c010 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
2c020 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
2c030 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
2c040 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
2c050 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
2c060 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
2c070 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
2c080 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2c090 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
2c0a0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
2c0b0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
2c0c0 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
2c0d0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
2c0e0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
2c0f0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
2c100 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
2c110 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
2c120 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
2c130 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
2c140 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
2c150 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
2c160 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
2c170 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
2c180 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
2c190 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
2c1a0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2c1b0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
2c1c0 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
2c1d0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
2c1e0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
2c1f0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
2c200 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
2c210 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
2c220 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
2c230 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2c240 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2c250 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2c260 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c270 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2c280 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2c290 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2c2a0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2c2b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2c2c0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2c2d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2c2e0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2c2f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2c300 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2c310 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
2c320 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
2c330 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
2c340 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
2c350 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  me.**.** ^Return
2c360 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
2c370 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
2c380 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
2c390 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
2c3a0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
2c3b0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
2c3c0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
2c3d0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
2c3e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2c3f0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2c400 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
2c410 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
2c420 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
2c430 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
2c440 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
2c450 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
2c460 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
2c470 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
2c480 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
2c490 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
2c4a0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
2c4b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
2c4c0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2c4d0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2c4e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2c4f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2c500 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2c510 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2c520 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2c530 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2c540 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2c550 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2c560 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2c570 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
2c580 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
2c590 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
2c5a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c5b0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
2c5c0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
2c5d0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
2c5e0 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
2c5f0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
2c600 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
2c610 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
2c620 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
2c630 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2c640 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
2c650 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2c660 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
2c670 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
2c680 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
2c690 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
2c6a0 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  LL..*/.SQLITE_AP
2c6b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  I int sqlite3_cl
2c6c0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
2c6d0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2c6e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2c6f0 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
2c700 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2c710 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
2c720 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2c730 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
2c740 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
2c750 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
2c760 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
2c770 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
2c780 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
2c790 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
2c7a0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
2c7b0 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
2c7c0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
2c7d0 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a   [UPDATE])..**.*
2c7e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2c7f0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c800 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
2c810 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2c820 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2c830 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2c840 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c850 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2c860 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2c870 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2c880 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2c890 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2c8a0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2c8b0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2c8c0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2c8d0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2c8e0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2c8f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2c900 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c910 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2c920 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2c930 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2c940 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2c950 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2c960 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2c970 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2c980 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2c990 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2c9a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2c9b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2c9c0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2c9d0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2c9e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2c9f0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2ca00 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2ca10 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2ca20 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2ca30 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2ca40 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2ca50 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2ca60 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2ca70 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2ca80 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ca90 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2caa0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2cab0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2cac0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2cad0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2cae0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2caf0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2cb00 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2cb10 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2cb20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2cb30 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2cb40 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2cb50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cb60 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2cb70 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2cb80 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2cb90 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2cba0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2cbb0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2cbc0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2cbd0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2cbe0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2cbf0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2cc00 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2cc10 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2cc20 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2cc30 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2cc40 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2cc50 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2cc60 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2cc70 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2cc80 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2cc90 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2cca0 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2ccb0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2ccc0 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2ccd0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2cce0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2ccf0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2cd00 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2cd10 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2cd20 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2cd30 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2cd40 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2cd50 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
2cd60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2cd70 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20   N);.SQLITE_API 
2cd80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2cd90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2cda0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2cdb0 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
2cdc0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
2cdd0 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
2cde0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
2cdf0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2ce00 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
2ce10 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
2ce20 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
2ce30 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
2ce40 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
2ce50 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
2ce60 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
2ce70 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
2ce80 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2ce90 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
2cea0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
2ceb0 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
2cec0 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
2ced0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
2cee0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
2cef0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
2cf00 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
2cf10 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
2cf20 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
2cf30 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
2cf40 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2cf50 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
2cf60 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
2cf70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2cf80 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
2cf90 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2cfa0 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
2cfb0 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
2cfc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cfd0 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
2cfe0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2cff0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2d000 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2d010 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2d020 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2d030 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2d040 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2d050 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2d060 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2d070 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
2d080 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2d090 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
2d0a0 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
2d0b0 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
2d0c0 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
2d0d0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
2d0e0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
2d0f0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
2d100 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
2d110 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
2d120 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2d130 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
2d140 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
2d150 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2d160 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
2d170 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2d180 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2d190 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
2d1a0 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
2d1b0 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
2d1c0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
2d1d0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
2d1e0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2d1f0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
2d200 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
2d210 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
2d220 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
2d230 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2d240 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
2d250 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2d260 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
2d270 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
2d280 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
2d290 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
2d2a0 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
2d2b0 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
2d2c0 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
2d2d0 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
2d2e0 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
2d2f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2d300 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
2d310 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
2d320 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
2d330 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
2d340 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
2d350 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
2d360 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
2d370 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
2d380 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
2d390 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
2d3a0 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
2d3b0 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
2d3c0 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
2d3d0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
2d3e0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2d3f0 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
2d400 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
2d410 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
2d420 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
2d430 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
2d440 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
2d450 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
2d460 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
2d470 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
2d480 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
2d490 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
2d4a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2d4b0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2d4c0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
2d4d0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2d4e0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
2d4f0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
2d500 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
2d510 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
2d520 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2d530 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
2d540 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
2d550 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2d560 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2d570 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
2d580 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2d590 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
2d5a0 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
2d5b0 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
2d5c0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
2d5d0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
2d5e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
2d5f0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2d600 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2d610 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2d620 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2d630 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2d640 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2d650 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2d660 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2d670 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2d680 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2d690 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
2d6a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2d6b0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2d6c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2d6d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2d6e0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2d6f0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2d700 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2d710 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d720 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
2d730 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2d740 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2d750 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2d760 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2d770 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2d780 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2d790 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2d7a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2d7b0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
2d7c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2d7d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d7e0 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
2d7f0 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
2d800 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ult.**.** ^(The 
2d810 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2d820 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2d830 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
2d840 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
2d850 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
2d860 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
2d870 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2d880 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
2d890 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
2d8a0 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
2d8b0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
2d8c0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2d8d0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
2d8e0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
2d8f0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
2d900 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
2d910 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
2d920 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2d930 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2d940 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
2d950 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2d960 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
2d970 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2d980 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
2d990 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
2d9a0 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
2d9b0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2d9c0 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
2d9d0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
2d9e0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
2d9f0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
2da00 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
2da10 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
2da20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2da30 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
2da40 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
2da50 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
2da60 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
2da70 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
2da80 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
2da90 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
2daa0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
2dab0 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
2dac0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
2dad0 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
2dae0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
2daf0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
2db00 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
2db10 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
2db20 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
2db30 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
2db40 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
2db50 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
2db60 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
2db70 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
2db80 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
2db90 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
2dba0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2dbb0 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
2dbc0 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
2dbd0 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
2dbe0 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
2dbf0 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
2dc00 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
2dc10 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
2dc20 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
2dc30 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
2dc40 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
2dc50 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53  ose values..*/.S
2dc60 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2dc70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2dc80 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
2dc90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2dca0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2dcb0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2dcc0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2dcd0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2dce0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2dcf0 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
2dd00 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2dd10 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
2dd20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2dd30 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
2dd40 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
2dd50 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2dd60 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2dd70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2dd80 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
2dd90 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
2dda0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
2ddb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2ddc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2ddd0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
2dde0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
2ddf0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
2de00 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
2de10 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
2de20 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
2de30 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
2de40 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
2de50 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2de60 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
2de70 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
2de80 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
2de90 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2dea0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
2deb0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
2dec0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ded0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2dee0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2def0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
2df00 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2df10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2df20 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2df30 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
2df40 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
2df50 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
2df60 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2df70 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
2df80 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
2df90 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2dfa0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
2dfb0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
2dfc0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
2dfd0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2dfe0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
2dff0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
2e000 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
2e010 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
2e020 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
2e030 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
2e040 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
2e050 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
2e060 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2e070 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
2e080 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
2e090 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
2e0a0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
2e0b0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
2e0c0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
2e0d0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
2e0e0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
2e0f0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
2e100 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
2e110 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
2e120 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
2e130 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
2e140 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
2e150 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
2e160 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
2e170 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
2e180 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
2e190 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
2e1a0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
2e1b0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
2e1c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2e1d0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
2e1e0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
2e1f0 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
2e200 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
2e210 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
2e220 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
2e230 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
2e240 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
2e250 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
2e260 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2e270 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
2e280 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
2e290 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
2e2a0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
2e2b0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2e2c0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2e2d0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
2e2e0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
2e2f0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
2e300 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e310 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
2e320 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
2e330 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2e340 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
2e350 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
2e360 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
2e370 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
2e380 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
2e390 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
2e3a0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
2e3b0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
2e3c0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
2e3d0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
2e3e0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
2e3f0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
2e400 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
2e410 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
2e420 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
2e430 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2e440 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
2e450 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
2e460 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
2e470 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
2e480 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
2e490 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
2e4a0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
2e4b0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
2e4c0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
2e4d0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
2e4e0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
2e4f0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
2e500 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
2e510 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
2e520 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
2e530 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2e540 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
2e550 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
2e560 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
2e570 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2e580 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
2e590 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
2e5a0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
2e5b0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
2e5c0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
2e5d0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
2e5e0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
2e5f0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2e600 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
2e610 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2e620 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
2e630 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
2e640 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
2e650 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2e660 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
2e670 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
2e680 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
2e690 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
2e6a0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
2e6b0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
2e6c0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
2e6d0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
2e6e0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
2e6f0 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
2e700 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e710 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
2e720 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
2e730 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2e740 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
2e750 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
2e760 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
2e770 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2e780 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2e790 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
2e7a0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
2e7b0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
2e7c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e7d0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
2e7e0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
2e7f0 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
2e800 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
2e810 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
2e820 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
2e830 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
2e840 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
2e850 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
2e860 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e870 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
2e880 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
2e890 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
2e8a0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
2e8b0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2e8c0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
2e8d0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
2e8e0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
2e8f0 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
2e900 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
2e910 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e920 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
2e930 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
2e940 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
2e950 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2e960 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
2e970 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2e980 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69   But after versi
2e990 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c  on 3.6.23.1, sql
2e9a0 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
2e9b0 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
2e9c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
2e9d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
2e9e0 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
2e9f0 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
2ea00 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2ea10 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
2ea20 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
2ea30 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
2ea40 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
2ea50 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
2ea60 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
2ea70 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
2ea80 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
2ea90 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
2eaa0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
2eab0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
2eac0 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
2ead0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
2eae0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
2eaf0 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
2eb00 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2eb10 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
2eb20 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
2eb30 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2eb40 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
2eb50 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
2eb60 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
2eb70 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
2eb80 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
2eb90 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
2eba0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
2ebb0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2ebc0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
2ebd0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
2ebe0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
2ebf0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2ec00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2ec10 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
2ec20 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
2ec30 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
2ec40 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
2ec50 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
2ec60 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
2ec70 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
2ec80 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
2ec90 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
2eca0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
2ecb0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
2ecc0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
2ecd0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
2ece0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
2ecf0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
2ed00 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
2ed10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2ed20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2ed30 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
2ed40 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
2ed50 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
2ed60 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2ed70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ed80 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
2ed90 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
2eda0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
2edb0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
2edc0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
2edd0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
2ede0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
2edf0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2ee00 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2ee10 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
2ee20 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
2ee30 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
2ee40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ee50 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
2ee60 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
2ee70 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t set.**.** ^The
2ee80 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2ee90 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
2eea0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2eeb0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2eec0 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
2eed0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2eee0 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
2eef0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2ef00 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
2ef10 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
2ef20 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
2ef30 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
2ef40 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
2ef50 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
2ef60 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
2ef70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
2ef80 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
2ef90 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
2efa0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2efb0 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
2efc0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2efd0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2efe0 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
2eff0 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
2f000 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
2f010 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2f020 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
2f030 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
2f040 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
2f050 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2f060 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
2f070 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
2f080 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2f090 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
2f0a0 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
2f0b0 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
2f0c0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2f0d0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
2f0e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
2f0f0 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
2f100 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
2f110 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
2f120 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
2f130 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
2f140 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
2f150 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
2f160 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
2f170 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
2f180 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
2f190 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2f1a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2f1b0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
2f1c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2f1d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
2f1e0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2f1f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f200 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
2f210 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
2f220 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
2f230 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
2f240 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
2f250 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
2f260 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
2f270 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
2f280 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
2f290 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2f2a0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2f2b0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
2f2c0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
2f2d0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
2f2e0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
2f2f0 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
2f300 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2f310 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
2f320 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
2f330 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
2f340 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
2f350 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
2f360 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
2f370 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
2f380 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
2f390 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
2f3a0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
2f3b0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
2f3c0 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
2f3d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
2f3e0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
2f3f0 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
2f400 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
2f410 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
2f420 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2f430 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
2f440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
2f450 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
2f460 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
2f470 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2f480 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
2f490 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2f4a0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
2f4b0 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
2f4c0 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
2f4d0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
2f4e0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
2f4f0 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
2f500 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
2f510 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
2f520 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
2f530 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
2f540 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2f550 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
2f560 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
2f570 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  set" interface..
2f580 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2f590 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
2f5a0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
2f5b0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
2f5c0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
2f5d0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
2f5e0 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
2f5f0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
2f600 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
2f610 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2f620 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f630 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
2f640 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
2f650 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2f660 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
2f670 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
2f680 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2f690 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
2f6a0 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
2f6b0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
2f6c0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2f6d0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
2f6e0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
2f6f0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
2f700 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
2f710 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2f720 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2f730 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
2f740 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
2f750 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2f760 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2f770 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
2f780 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2f790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2f7a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
2f7b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2f7c0 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
2f7d0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
2f7e0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
2f7f0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
2f800 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2f810 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
2f820 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2f830 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2f840 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
2f850 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
2f860 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
2f870 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2f880 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
2f890 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
2f8a0 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
2f8b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
2f8c0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2f8d0 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
2f8e0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
2f8f0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
2f900 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2f910 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
2f920 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
2f930 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2f940 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2f950 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
2f960 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2f970 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
2f980 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
2f990 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
2f9a0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2f9b0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
2f9c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2f9d0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2f9e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2f9f0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
2fa00 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
2fa10 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2fa20 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
2fa30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2fa40 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
2fa50 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2fa60 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2fa70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fa80 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
2fa90 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2faa0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
2fab0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2fac0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
2fad0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
2fae0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
2faf0 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
2fb00 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
2fb10 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2fb20 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
2fb30 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
2fb40 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
2fb50 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
2fb60 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
2fb70 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
2fb80 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2fb90 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2fba0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
2fbb0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
2fbc0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
2fbd0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
2fbe0 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
2fbf0 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
2fc00 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
2fc10 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
2fc20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fc30 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
2fc40 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
2fc50 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2fc60 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
2fc70 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
2fc80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2fc90 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
2fca0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2fcb0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
2fcc0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2fcd0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
2fce0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2fcf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fd00 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2fd10 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2fd20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2fd30 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2fd40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2fd50 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
2fd60 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2fd70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fd80 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2fd90 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2fda0 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
2fdb0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2fdc0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2fdd0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2fde0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2fdf0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2fe00 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
2fe10 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2fe20 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2fe30 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2fe40 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
2fe50 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2fe60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2fe70 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2fe80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2fe90 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2fea0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2feb0 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
2fec0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
2fed0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2fee0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
2fef0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2ff00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ff10 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
2ff20 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2ff30 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2ff40 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2ff50 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2ff60 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2ff70 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
2ff80 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2ff90 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
2ffa0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2ffb0 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
2ffc0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2ffd0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2ffe0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2fff0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
30000 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
30010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30020 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
30030 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
30040 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
30050 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
30060 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
30070 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
30080 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
30090 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
300a0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
300b0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
300c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
300d0 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
300e0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
300f0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
30100 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
30110 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
30120 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
30130 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
30140 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
30150 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
30160 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
30170 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
30180 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
30190 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
301a0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
301b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
301c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
301d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
301e0 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
301f0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
30200 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
30210 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
30220 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
30230 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
30240 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
30250 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
30260 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30270 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
30280 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
30290 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
302a0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
302b0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
302c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
302d0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
302e0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
302f0 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
30300 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
30310 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
30320 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
30330 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
30340 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
30350 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30360 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
30370 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30380 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
30390 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
303a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
303b0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
303c0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
303d0 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
303e0 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
303f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30400 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
30410 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
30420 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
30430 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
30440 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
30450 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
30460 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
30470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
30480 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
30490 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
304a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
304b0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
304c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
304d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
304e0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
304f0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
30500 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
30510 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
30520 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
30530 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
30540 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
30550 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
30560 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
30570 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
30580 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
30590 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
305a0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
305b0 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
305c0 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
305d0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
305e0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
305f0 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
30600 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
30610 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
30620 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
30630 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
30640 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
30650 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
30660 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
30670 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
30680 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
30690 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
306a0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
306b0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
306c0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
306d0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
306e0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
306f0 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
30700 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
30710 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
30720 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
30730 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
30740 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
30750 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
30760 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
30770 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
30780 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
30790 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
307a0 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
307b0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
307c0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
307d0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
307e0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
307f0 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
30800 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
30810 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
30820 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
30830 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
30840 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
30850 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
30860 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
30870 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f  rt from float to
30880 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
30890 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
308a0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
308b0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
308c0 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
308d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
308e0 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
308f0 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
30900 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c  FLOAT->TEXT.** <
30910 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
30920 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
30930 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a  <td> Use atoi().
30940 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
30950 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
30960 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f      <td> Use ato
30970 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
30980 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
30990 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
309a0 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
309b0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
309c0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
309d0 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
309e0 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a  then use atoi().
309f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
30a00 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
30a10 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
30a20 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
30a30 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
30a40 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
30a50 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
30a60 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
30a70 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
30a80 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
30a90 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
30aa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
30ab0 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
30ac0 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
30ad0 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
30ae0 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
30af0 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
30b00 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
30b10 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
30b20 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
30b30 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
30b40 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
30b50 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
30b60 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
30b70 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
30b80 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
30b90 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
30ba0 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
30bb0 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
30bc0 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
30bd0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
30be0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
30bf0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
30c00 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
30c10 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
30c20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
30c30 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
30c40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30c50 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
30c60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30c70 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
30c80 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
30c90 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
30ca0 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
30cb0 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
30cc0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
30cd0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
30ce0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
30cf0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
30d00 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
30d10 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
30d20 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
30d30 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
30d40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
30d50 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
30d60 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
30d70 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
30d80 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
30d90 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
30da0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
30db0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
30dc0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
30dd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30de0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
30df0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
30e00 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
30e10 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
30e20 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
30e30 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
30e40 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
30e50 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
30e60 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
30e70 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
30e80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30e90 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
30ea0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30eb0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
30ec0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
30ed0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
30ee0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
30ef0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
30f00 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
30f10 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
30f20 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
30f30 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
30f40 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
30f50 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
30f60 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
30f70 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
30f80 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
30f90 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
30fa0 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
30fb0 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65  ointer reference
30fc0 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  s will have been
30fd0 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
30fe0 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
30ff0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
31000 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
31010 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
31020 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
31030 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
31040 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
31050 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
31060 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
31070 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
31080 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
31090 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
310a0 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
310b0 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
310c0 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
310d0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
310e0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
310f0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
31100 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
31110 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
31120 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31130 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
31140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31150 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
31160 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
31170 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
31180 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
31190 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
311a0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
311b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
311c0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
311d0 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
311e0 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
311f0 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
31200 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
31210 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31220 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
31230 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
31240 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
31250 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
31260 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
31270 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
31280 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
31290 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
312a0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
312b0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
312c0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
312d0 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
312e0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
312f0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
31300 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
31310 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
31320 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
31330 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
31340 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
31350 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
31360 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
31370 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
31380 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
31390 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
313a0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
313b0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
313c0 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
313d0 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
313e0 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
313f0 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
31400 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
31410 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
31420 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31430 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
31440 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
31450 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
31460 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
31470 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
31480 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
31490 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
314a0 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
314b0 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
314c0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
314d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
314e0 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
314f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
31500 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
31510 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
31520 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
31530 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
31540 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
31550 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
31560 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
31570 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
31580 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
31590 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
315a0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
315b0 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
315c0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
315d0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
315e0 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
315f0 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
31600 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
31610 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
31620 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
31630 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
31640 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
31650 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
31660 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
31670 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
31680 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31690 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
316a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
316b0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
316c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
316d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
316e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
316f0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
31700 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
31710 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f  );.SQLITE_API do
31720 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
31730 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
31740 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31750 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
31760 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
31770 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
31780 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31790 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
317a0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
317b0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
317c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
317d0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
317e0 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
317f0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
31800 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
31810 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31820 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
31830 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
31840 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
31850 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
31860 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
31870 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
31880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
31890 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
318a0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
318b0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61  E_API sqlite3_va
318c0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
318d0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
318e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
318f0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
31900 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
31910 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
31920 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e  t Object.**.** ^
31930 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
31940 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
31950 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
31960 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
31970 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
31980 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
31990 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
319a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
319b0 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
319c0 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
319d0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
319e0 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
319f0 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
31a00 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
31a10 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
31a20 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
31a30 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
31a40 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
31a50 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
31a60 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
31a70 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
31a80 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
31a90 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
31aa0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
31ab0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
31ac0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
31ad0 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
31ae0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
31af0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
31b00 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
31b10 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
31b20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
31b30 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
31b40 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
31b50 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
31b60 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
31b70 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
31b80 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
31b90 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
31ba0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
31bb0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
31bc0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
31bd0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
31be0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
31bf0 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
31c00 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
31c10 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
31c20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
31c30 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
31c40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
31c50 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
31c60 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
31c70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31c80 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
31c90 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
31ca0 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
31cb0 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
31cc0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
31cd0 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
31ce0 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
31cf0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
31d00 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
31d10 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
31d20 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
31d30 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
31d40 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
31d50 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
31d60 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
31d70 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
31d80 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
31d90 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
31da0 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
31db0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
31dc0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
31dd0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
31de0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
31df0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
31e00 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
31e10 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
31e20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
31e30 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
31e40 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
31e50 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
31e60 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
31e70 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
31e80 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
31e90 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
31ea0 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
31eb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
31ec0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
31ed0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
31ee0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
31ef0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
31f00 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
31f10 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
31f20 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
31f30 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
31f40 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
31f50 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
31f60 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
31f70 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
31f80 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
31f90 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
31fa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31fb0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
31fc0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
31fd0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
31fe0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
31ff0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
32000 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
32010 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
32020 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32030 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
32040 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
32050 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
32060 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
32070 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
32080 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
32090 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
320a0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
320b0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
320c0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
320d0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
320e0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
320f0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
32100 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
32110 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
32120 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
32130 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
32140 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
32150 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
32160 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
32170 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
32180 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
32190 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
321a0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
321b0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
321c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
321d0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
321e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
321f0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
32200 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
32210 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
32220 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
32230 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32240 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
32250 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
32260 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
32270 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
32280 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
32290 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
322a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
322b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
322c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
322d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
322e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
322f0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
32300 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
32310 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
32320 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
32330 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
32340 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
32350 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
32360 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
32370 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
32380 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
32390 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
323a0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
323b0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
323c0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
323d0 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
323e0 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
323f0 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
32400 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
32410 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
32420 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
32430 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
32440 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
32450 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
32460 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
32470 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
32480 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
32490 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
324a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
324b0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
324c0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
324d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
324e0 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
324f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
32500 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
32510 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
32520 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
32530 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
32540 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
32550 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32560 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
32570 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
32580 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
32590 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
325a0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
325b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
325c0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
325d0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
325e0 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
325f0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
32600 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
32610 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
32620 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
32630 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
32640 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
32650 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
32660 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
32670 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
32680 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
32690 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
326a0 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
326b0 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
326c0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
326d0 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
326e0 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
326f0 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
32700 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
32710 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
32720 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
32730 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
32740 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
32750 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
32760 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
32770 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
32780 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
32790 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
327a0 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
327b0 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
327c0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
327d0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
327e0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
327f0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
32800 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
32810 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
32820 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
32830 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
32840 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
32850 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
32860 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
32870 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
32880 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
32890 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
328a0 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
328b0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
328c0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
328d0 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
328e0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
328f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
32900 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
32910 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
32920 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
32930 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
32940 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74   Every SQL funct
32950 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
32960 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20  on must be able 
32970 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20  to work.** with 
32980 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
32990 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
329a0 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
329b0 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
329c0 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
329d0 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
329e0 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
329f0 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
32a00 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
32a10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32a20 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
32a30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32a40 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
32a50 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
32a60 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
32a70 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
32a80 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
32a90 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
32aa0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
32ab0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
32ac0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
32ad0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
32ae0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
32af0 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
32b00 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
32b10 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
32b20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
32b30 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
32b40 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
32b50 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
32b60 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
32b70 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
32b80 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
32b90 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
32ba0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
32bb0 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
32bc0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
32bd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
32be0 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
32bf0 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
32c00 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
32c10 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
32c20 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
32c30 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
32c40 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
32c50 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
32c60 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
32c70 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
32c80 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
32c90 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
32ca0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
32cb0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
32cc0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
32cd0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
32ce0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
32cf0 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
32d00 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
32d10 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
32d20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32d30 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
32d40 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
32d50 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
32d60 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
32d70 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
32d80 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
32d90 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
32da0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
32db0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
32dc0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
32dd0 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
32de0 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
32df0 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
32e00 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
32e10 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
32e20 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
32e30 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
32e40 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
32e50 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
32e60 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
32e70 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
32e80 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
32e90 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
32ea0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
32eb0 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
32ec0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
32ed0 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
32ee0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
32ef0 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
32f00 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
32f10 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
32f20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
32f30 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
32f40 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
32f50 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
32f60 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
32f70 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
32f80 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
32f90 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
32fa0 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
32fb0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
32fc0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
32fd0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
32fe0 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
32ff0 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
33000 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
33010 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
33020 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
33030 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
33040 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
33050 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33060 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
33070 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
33080 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
33090 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
330a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
330b0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
330c0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
330d0 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
330e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
330f0 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
33100 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
33110 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
33120 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
33130 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
33140 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
33150 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
33160 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
33170 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
33180 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
33190 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
331a0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
331b0 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
331c0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
331d0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
331e0 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
331f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33200 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
33210 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
33220 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
33230 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
33240 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
33250 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
33260 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
33270 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
33280 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
33290 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
332a0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
332b0 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
332c0 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
332d0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
332e0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
332f0 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
33300 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
33310 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
33320 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
33330 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
33340 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
33350 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
33360 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
33370 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
33380 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
33390 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
333a0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
333b0 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
333c0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
333d0 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
333e0 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
333f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33400 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
33410 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33420 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
33430 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
33440 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
33450 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
33460 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
33470 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
33480 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
33490 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
334a0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
334b0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
334c0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
334d0 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
334e0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
334f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
33500 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
33510 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
33520 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
33530 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
33540 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
33550 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
33560 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
33570 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
33580 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33590 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
335a0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
335b0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
335c0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
335d0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
335e0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
335f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33600 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
33610 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
33620 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
33630 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
33640 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
33650 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
33660 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
33670 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
33680 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
33690 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
336a0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
336b0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
336c0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
336d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
336e0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
336f0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
33700 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
33710 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
33720 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
33730 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
33740 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
33750 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
33760 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
33770 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
33780 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
33790 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
337a0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
337b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
337c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
337d0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
337e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
337f0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
33800 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
33810 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
33820 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
33830 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
33840 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
33850 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
33860 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
33870 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
33880 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
33890 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
338a0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
338b0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
338c0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
338d0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
338e0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
338f0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
33900 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
33910 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
33920 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
33930 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
33940 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
33950 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
33960 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
33970 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
33980 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
33990 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
339a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
339b0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
339c0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
339d0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
339e0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
339f0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
33a00 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
33a10 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
33a20 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
33a30 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
33a40 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
33a50 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
33a60 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
33a70 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
33a80 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
33a90 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
33aa0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
33ab0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
33ac0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
33ad0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
33ae0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
33af0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
33b00 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
33b10 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
33b20 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
33b30 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
33b40 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
33b50 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
33b60 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
33b70 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
33b80 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
33b90 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
33ba0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
33bb0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
33bc0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
33bd0 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
33be0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
33bf0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
33c00 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
33c10 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
33c20 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
33c30 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
33c40 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
33c50 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
33c60 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
33c70 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
33c80 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
33c90 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
33ca0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
33cb0 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
33cc0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
33cd0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
33ce0 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
33cf0 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
33d00 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
33d10 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
33d20 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
33d30 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
33d40 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
33d50 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
33d60 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
33d70 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
33d80 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
33d90 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
33da0 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
33db0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
33dc0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
33dd0 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
33de0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
33df0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
33e00 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
33e10 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
33e20 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
33e30 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
33e40 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
33e50 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
33e60 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
33e70 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
33e80 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
33e90 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
33ea0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
33eb0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33ec0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
33ed0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33ee0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
33ef0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
33f00 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
33f10 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
33f20 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
33f30 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
33f40 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
33f50 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
33f60 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
33f70 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
33f80 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
33f90 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
33fa0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
33fb0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
33fc0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
33fd0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
33fe0 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
33ff0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
34000 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
34010 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
34020 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
34030 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
34040 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
34050 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
34060 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
34070 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34080 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
34090 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
340a0 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
340b0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
340c0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
340d0 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
340e0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
340f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
34100 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
34110 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
34120 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
34130 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
34140 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
34150 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
34160 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
34170 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
34180 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34190 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
341a0 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
341b0 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
341c0 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
341d0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
341e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
341f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
34200 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
34210 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
34220 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
34230 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
34240 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
34250 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
34260 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34270 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
34280 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34290 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
342a0 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
342b0 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
342c0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
342d0 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
342e0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
342f0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
34300 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
34310 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
34320 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
34330 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
34340 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
34350 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
34360 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
34370 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
34380 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
34390 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
343a0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
343b0 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
343c0 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
343d0 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
343e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
343f0 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
34400 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
34410 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
34420 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
34430 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
34440 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
34450 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
34460 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
34470 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
34480 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
34490 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
344a0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
344b0 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
344c0 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
344d0 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
344e0 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
344f0 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
34500 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
34510 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34520 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
34530 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
34540 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
34550 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
34560 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
34570 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
34580 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
34590 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
345a0 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
345b0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
345c0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
345d0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
345e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
345f0 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
34600 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
34610 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
34620 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
34630 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
34640 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
34650 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
34660 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
34670 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49  ameters..*/.SQLI
34680 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
34690 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
346a0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
346b0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
346c0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
346d0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
346e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
346f0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
34700 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
34710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34720 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
34730 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
34740 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
34750 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
34760 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34770 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
34780 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34790 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
347a0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
347b0 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
347c0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
347d0 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
347e0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
347f0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
34800 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
34810 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
34820 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
34830 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
34840 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
34850 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
34860 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
34870 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
34880 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
34890 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
348a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
348b0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
348c0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
348d0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
348e0 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
348f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34900 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
34910 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
34920 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
34930 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
34940 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
34950 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
34960 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
34970 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
34980 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
34990 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
349a0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
349b0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
349c0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
349d0 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
349e0 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
349f0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
34a00 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
34a10 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
34a20 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
34a30 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
34a40 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
34a50 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
34a60 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
34a70 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
34a80 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
34a90 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
34aa0 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
34ab0 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
34ac0 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
34ad0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
34ae0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
34af0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
34b00 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
34b10 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
34b20 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
34b30 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
34b40 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
34b50 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
34b60 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
34b70 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
34b80 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
34b90 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
34ba0 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
34bb0 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
34bc0 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
34bd0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
34be0 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
34bf0 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
34c00 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
34c10 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
34c20 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
34c30 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
34c40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
34c50 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
34c60 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
34c70 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
34c80 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
34c90 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
34ca0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34cb0 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
34cc0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
34cd0 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
34ce0 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
34cf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34d00 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34d10 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
34d20 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
34d30 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73   pointer if N is
34d40 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  .** less than or
34d50 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
34d60 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
34d70 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
34d80 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
34d90 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
34da0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
34db0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
34dc0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
34dd0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
34de0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
34df0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
34e00 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
34e10 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
34e20 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
34e30 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
34e40 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34e50 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
34e60 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
34e70 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
34e80 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
34e90 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
34ea0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
34eb0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
34ec0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
34ed0 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
34ee0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
34ef0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
34f00 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
34f10 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
34f20 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
34f30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
34f40 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
34f50 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
34f60 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
34f70 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
34f80 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
34f90 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
34fa0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
34fb0 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
34fc0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
34fd0 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
34fe0 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
34ff0 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
35000 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
35010 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
35020 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
35030 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
35040 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
35050 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
35060 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
35070 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
35080 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
35090 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
350a0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
350b0 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
350c0 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
350d0 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
350e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
350f0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
35100 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35110 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
35120 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
35130 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
35140 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
35150 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
35160 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
35170 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35180 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
35190 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
351a0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
351b0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
351c0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
351d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
351e0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
351f0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
35200 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
35210 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
35220 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
35230 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
35240 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35250 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
35260 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
35270 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75   void *sqlite3_u
35280 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
35290 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
352a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
352b0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
352c0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
352d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
352e0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
352f0 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
35300 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
35310 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
35320 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
35330 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
35340 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
35350 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
35360 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
35370 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
35380 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35390 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
353a0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
353b0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
353c0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
353d0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
353e0 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
353f0 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c  API sqlite3 *sql
35400 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
35410 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
35420 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
35430 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
35440 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
35450 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  ta.**.** The fol
35460 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
35470 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
35480 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
35490 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
354a0 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
354b0 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
354c0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
354d0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
354e0 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
354f0 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
35500 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
35510 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
35520 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
35530 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
35540 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
35550 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
35560 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
35570 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a  rved. This may.*
35580 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  * be used, for e
35590 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61  xample, to add a
355a0 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
355b0 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61  ion matching sca
355c0 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  lar.** function.
355d0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
355e0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
355f0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
35600 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  is stored as.** 
35610 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
35620 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
35630 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
35640 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
35650 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
35660 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
35670 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
35680 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
35690 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
356a0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
356b0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
356c0 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
356d0 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
356e0 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
356f0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
35700 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
35710 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
35720 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35730 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
35740 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35750 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
35760 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
35770 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
35780 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35790 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
357a0 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
357b0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
357c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
357d0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
357e0 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  . ^If no metadat
357f0 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
35800 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
35810 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
35820 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
35830 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
35840 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
35850 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
35860 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
35870 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
35880 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
35890 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
358a0 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
358b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
358c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
358d0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
358e0 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
358f0 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
35900 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
35910 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
35920 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  as the metadata 
35930 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
35940 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
35950 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35960 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
35970 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
35980 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
35990 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
359a0 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
359b0 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
359c0 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
359d0 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  yed..** ^If it i
359e0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
359f0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
35a00 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
35a10 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
35a20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
35a30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
35a40 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
35a50 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61  .** the metadata
35a60 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
35a70 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
35a80 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
35a90 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
35aa0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
35ab0 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
35ac0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
35ad0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
35ae0 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74  s free to call t
35af0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e  he destructor an
35b00 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20  d drop metadata 
35b10 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65  on any.** parame
35b20 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74  ter of any funct
35b30 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e  ion at any time.
35b40 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72    ^The only guar
35b50 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a  antee is that.**
35b60 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
35b70 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  will be called b
35b80 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61  efore the metada
35b90 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a  ta is dropped..*
35ba0 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
35bb0 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
35bc0 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
35bd0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
35be0 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
35bf0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
35c00 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
35c10 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
35c20 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
35c30 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61  values and [para
35c40 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  meters].)^.**.**
35c50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
35c60 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
35c70 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
35c80 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
35c90 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
35ca0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
35cb0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
35cc0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
35cd0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
35ce0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  text*, int N);.S
35cf0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
35d00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35d10 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
35d20 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
35d30 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
35d40 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
35d50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
35d60 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
35d70 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
35d80 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
35d90 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
35da0 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
35db0 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
35dc0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
35dd0 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
35de0 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
35df0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
35e00 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
35e10 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
35e20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
35e30 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
35e40 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
35e50 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
35e60 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
35e70 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
35e80 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
35e90 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
35ea0 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
35eb0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
35ec0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
35ed0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
35ee0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
35ef0 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
35f00 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
35f10 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
35f20 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
35f30 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
35f40 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
35f50 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
35f60 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
35f70 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
35f80 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
35f90 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
35fa0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
35fb0 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
35fc0 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
35fd0 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
35fe0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
35ff0 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
36000 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
36010 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
36020 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
36030 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36040 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
36050 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
36060 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
36070 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
36080 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
36090 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
360a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
360b0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
360c0 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
360d0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
360e0 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
360f0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
36100 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
36110 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
36120 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36130 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
36140 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36150 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
36160 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
36170 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
36180 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
36190 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
361a0 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
361b0 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
361c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
361d0 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
361e0 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
361f0 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
36200 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
36210 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
36220 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
36230 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
36240 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
36250 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
36260 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36270 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
36280 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
36290 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
362a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
362b0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
362c0 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
362d0 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
362e0 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
362f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
36300 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
36310 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
36320 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
36330 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
36340 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36350 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
36360 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
36370 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
36380 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
36390 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
363a0 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
363b0 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
363c0 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
363d0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
363e0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
363f0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
36400 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
36410 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36420 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
36430 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
36440 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
36450 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
36460 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36470 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
36480 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
36490 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
364a0 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
364b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
364c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
364d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
364e0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
364f0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
36500 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
36510 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
36520 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
36530 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
36540 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
36550 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
36560 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
36570 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
36580 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
36590 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
365a0 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
365b0 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
365c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
365d0 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
365e0 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
365f0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
36600 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
36610 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
36620 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
36630 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
36640 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
36650 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
36660 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
36670 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
36680 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
36690 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
366a0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
366b0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
366c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
366d0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
366e0 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
366f0 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
36700 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
36710 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
36720 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
36730 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
36740 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
36750 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
36760 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
36770 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
36780 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
36790 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
367a0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
367b0 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
367c0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
367d0 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
367e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
367f0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
36800 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
36810 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36820 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
36830 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
36840 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
36850 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
36860 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
36870 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
36880 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
36890 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
368a0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
368b0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
368c0 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
368d0 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
368e0 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
368f0 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
36900 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
36910 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
36920 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
36930 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
36940 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
36950 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
36960 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
36970 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
36980 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
36990 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
369a0 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
369b0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
369c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
369d0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
369e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
369f0 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
36a00 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
36a10 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
36a20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36a30 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
36a40 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
36a50 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
36a60 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
36a70 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
36a80 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
36a90 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
36aa0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
36ab0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f  qlite3_result_no
36ac0 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
36ad0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
36ae0 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
36af0 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
36b00 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
36b10 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
36b20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36b30 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
36b40 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
36b50 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
36b60 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
36b70 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36b80 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
36b90 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
36ba0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
36bb0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
36bc0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
36bd0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36be0 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
36bf0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
36c00 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
36c10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36c20 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36c30 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
36c40 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
36c50 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
36c60 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
36c70 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
36c80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
36c90 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
36ca0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
36cb0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
36cc0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36cd0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36ce0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
36cf0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36d00 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
36d10 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
36d20 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
36d30 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
36d40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
36d50 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
36d60 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
36d70 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
36d80 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
36d90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36da0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
36db0 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
36dc0 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
36dd0 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
36de0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
36df0 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
36e00 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
36e10 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
36e20 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
36e30 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  y..** ^SQLite ta
36e40 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
36e50 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
36e60 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
36e70 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
36e80 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
36e90 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
36ea0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
36eb0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
36ec0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
36ed0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
36ee0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
36ef0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
36f00 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
36f10 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
36f20 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
36f30 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
36f40 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
36f50 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
36f60 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
36f70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
36f80 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
36f90 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
36fa0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
36fb0 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
36fc0 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
36fd0 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
36fe0 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
36ff0 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
37000 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
37010 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37020 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
37030 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64  ult.  If the 3rd
37040 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
37050 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
37060 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74   it.** must be t
37070 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69  he byte offset i
37080 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77  nto the string w
37090 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
370a0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a  minator would.**
370b0 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73   appear if the s
370c0 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20  tring where NUL 
370d0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
370e0 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
370f0 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  rs occur.** in t
37100 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62  he string at a b
37110 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20  yte offset that 
37120 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  is less than the
37130 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72   value of the 3r
37140 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20  d.** parameter, 
37150 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
37160 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63  ng string will c
37170 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
37180 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  NULs and the.** 
37190 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
371a0 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20  sions operating 
371b0 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20  on strings with 
371c0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
371d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
371e0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
371f0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
37200 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
37210 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
37220 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
37230 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
37240 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
37250 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
37260 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
37270 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
37280 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
37290 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
372a0 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
372b0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
372c0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
372d0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
372e0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
372f0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
37300 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
37310 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37320 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
37330 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
37340 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
37350 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
37360 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
37370 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
37380 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
37390 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
373a0 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
373b0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
373c0 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
373d0 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
373e0 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
373f0 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
37400 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
37410 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
37420 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
37430 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
37440 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
37450 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
37460 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
37470 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
37480 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
37490 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
374a0 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
374b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
374c0 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
374d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
374e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
374f0 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
37500 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
37510 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
37520 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
37530 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
37540 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
37550 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37560 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
37570 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
37580 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
37590 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
375a0 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
375b0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
375c0 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
375d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
375e0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
375f0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
37600 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
37610 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
37620 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
37630 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
37640 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
37650 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
37660 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
37670 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
37680 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
37690 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
376a0 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
376b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
376c0 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
376d0 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
376e0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
376f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
37700 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
37710 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
37720 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
37730 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37740 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
37750 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
37760 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
37770 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
37780 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
37790 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
377a0 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
377b0 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
377c0 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
377d0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
377e0 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
377f0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
37800 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
37810 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
37820 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
37830 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37840 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37850 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
37860 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
37870 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
37880 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
37890 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
378a0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
378b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
378c0 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54  , double);.SQLIT
378d0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
378e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
378f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37900 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
37910 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
37920 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37930 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
37940 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
37950 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
37960 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37970 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37980 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
37990 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
379a0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
379b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
379c0 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
379d0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
379e0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
379f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37a00 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
37a10 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
37a20 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37a30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
37a40 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
37a50 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  xt*, int);.SQLIT
37a60 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
37a70 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
37a80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37a90 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
37aa0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
37ab0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37ac0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
37ad0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
37ae0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
37af0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
37b00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
37b10 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
37b20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
37b30 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
37b40 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37b50 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
37b60 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37b70 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
37b80 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
37b90 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
37ba0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37bb0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
37bc0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
37bd0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
37be0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
37bf0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
37c00 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
37c10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37c20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
37c30 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
37c40 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
37c50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37c60 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ult_value(sqlite
37c70 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
37c80 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
37c90 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
37ca0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
37cb0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
37cc0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
37cd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37ce0 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
37cf0 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
37d00 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
37d10 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76  tions add, remov
37d20 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b  e, or modify a [
37d30 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63  collation] assoc
37d40 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
37d50 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37d60 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
37d70 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
37d80 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
37d90 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
37da0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55  collation is a U
37db0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
37dc0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
37dd0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
37de0 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
37df0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
37e00 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
37e10 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
37e20 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
37e30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37e40 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
37e50 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65   ^Collation name
37e60 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65  s that compare e
37e70 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74  qual according t
37e80 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69  o [sqlite3_strni
37e90 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f  cmp()] are.** co
37ea0 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74  nsidered to be t
37eb0 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
37ec0 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20  .** ^(The third 
37ed0 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52  argument (eTextR
37ee0 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  ep) must be one 
37ef0 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
37f00 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ul>.** <li
37f10 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  > [SQLITE_UTF8],
37f20 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
37f30 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16LE],.** <l
37f40 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
37f50 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BE],.** <li> [SQ
37f60 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a  LITE_UTF16], or.
37f70 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
37f80 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a  UTF16_ALIGNED]..
37f90 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54  ** </ul>)^.** ^T
37fa0 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
37fb0 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20  ment determines 
37fc0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
37fd0 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a  strings passed.*
37fe0 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  * to the collati
37ff0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
38000 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e  back, xCallback.
38010 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
38020 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c  _UTF16] and [SQL
38030 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
38040 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54  D] values for eT
38050 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20  extRep.** force 
38060 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54  strings to be UT
38070 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20  F16 with native 
38080 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
38090 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
380a0 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
380b0 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f   for eTextRep fo
380c0 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20  rces strings to 
380d0 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65  begin.** on an e
380e0 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73  ven byte address
380f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
38100 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41  rth argument, pA
38110 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63  rg, is an applic
38120 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
38130 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
38140 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20  d.** through as 
38150 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
38160 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  nt to the collat
38170 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
38180 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
38190 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
381a0 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20  , xCallback, is 
381b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
381c0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
381d0 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c  ion..** ^Multipl
381e0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
381f0 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67  tions can be reg
38200 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
38210 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a  e same name but.
38220 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ** with differen
38230 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d  t eTextRep param
38240 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65  eters and SQLite
38250 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65   will use whiche
38260 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ver.** function 
38270 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61  requires the lea
38280 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
38290 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e  a transformation
382a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61  ..** ^If the xCa
382b0 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
382c0 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
382d0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
382e0 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65  ion is.** delete
382f0 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f  d.  ^When all co
38300 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
38310 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d  s having the sam
38320 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74  e name are delet
38330 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c  ed,.** that coll
38340 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ation is no long
38350 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  er usable..**.**
38360 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20   ^The collating 
38370 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
38380 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
38390 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  h a copy of the 
383a0 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61  pArg .** applica
383b0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
383c0 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73  r and with two s
383d0 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e  trings in the en
383e0 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
383f0 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74  .** by the eText
38400 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Rep argument.  T
38410 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
38420 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72  ction must retur
38430 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  n an.** integer 
38440 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65  that is negative
38450 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74  , zero, or posit
38460 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69  ive.** if the fi
38470 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
38480 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74  ss than, equal t
38490 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
384a0 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a  an the second,.*
384b0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
384c0 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
384d0 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79  ction must alway
384e0 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
384f0 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65  e answer.** give
38500 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  n the same input
38510 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  s.  If two or mo
38520 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  re collating fun
38530 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73  ctions are regis
38540 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  tered.** to the 
38550 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e  same collation n
38560 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65  ame (using diffe
38570 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61  rent eTextRep va
38580 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a  lues) then all.*
38590 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65  * must give an e
385a0 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72  quivalent answer
385b0 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69   when invoked wi
385c0 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74  th equivalent st
385d0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f  rings..** The co
385e0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
385f0 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66   must obey the f
38600 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74  ollowing propert
38610 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73  ies for all.** s
38620 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64  trings A, B, and
38630 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a   C:.**.** <ol>.*
38640 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74  * <li> If A==B t
38650 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69  hen B==A..** <li
38660 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d  > If A==B and B=
38670 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a  =C then A==C..**
38680 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
38690 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20  THEN B&gt;A..** 
386a0 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61  <li> If A&lt;B a
386b0 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41  nd B&lt;C then A
386c0 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  &lt;C..** </ol>.
386d0 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61  **.** If a colla
386e0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61  ting function fa
386f0 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61  ils any of the a
38700 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  bove constraints
38710 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c   and that.** col
38720 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
38730 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61  is  registered a
38740 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  nd used, then th
38750 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  e behavior of SQ
38760 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  Lite.** is undef
38770 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
38780 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
38790 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
387a0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite