System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 97087b3d53260eeabad5894d4642a197397b1137:


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 36 2e 20 20  ersion 3.7.16.  
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 5a 45 52  *     SQLITE_ZER
3480: 4f 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  O_MALLOC        
3490: 20 20 20 20 2f 2f 20 55 73 65 20 61 20 73 74 75      // Use a stu
34a0: 62 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  b allocator that
34b0: 20 61 6c 77 61 79 73 20 66 61 69 6c 73 0a 2a 2a   always fails.**
34c0: 20 20 20 20 20 53 51 4c 49 54 45 5f 4d 45 4d 44       SQLITE_MEMD
34d0: 45 42 55 47 20 20 20 20 20 20 20 20 20 20 20 20  EBUG            
34e0: 20 20 20 2f 2f 20 44 65 62 75 67 67 69 6e 67 20     // Debugging 
34f0: 76 65 72 73 69 6f 6e 20 6f 66 20 73 79 73 74 65  version of syste
3500: 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a 2a 2a  m malloc().**.**
3510: 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69 66 20   On Windows, if 
3520: 74 68 65 20 53 51 4c 49 54 45 5f 57 49 4e 33 32  the SQLITE_WIN32
3530: 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41 54 45  _MALLOC_VALIDATE
3540: 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e 65   macro is define
3550: 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61 73 73  d and the.** ass
3560: 65 72 74 28 29 20 6d 61 63 72 6f 20 69 73 20 65  ert() macro is e
3570: 6e 61 62 6c 65 64 2c 20 65 61 63 68 20 63 61 6c  nabled, each cal
3580: 6c 20 69 6e 74 6f 20 74 68 65 20 57 69 6e 33 32  l into the Win32
3590: 20 6e 61 74 69 76 65 20 68 65 61 70 20 73 75 62   native heap sub
35a0: 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c 20 63  system.** will c
35b0: 61 75 73 65 20 48 65 61 70 56 61 6c 69 64 61 74  ause HeapValidat
35c0: 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e 20  e to be called. 
35d0: 20 49 66 20 68 65 61 70 20 76 61 6c 69 64 61 74   If heap validat
35e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69 6c 2c  ion should fail,
35f0: 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e   an.** assertion
3600: 20 77 69 6c 6c 20 62 65 20 74 72 69 67 67 65 72   will be trigger
3610: 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74 6f  ed..**.** (Histo
3620: 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54 68 65  rical note:  The
3630: 72 65 20 75 73 65 64 20 74 6f 20 62 65 20 73 65  re used to be se
3640: 76 65 72 61 6c 20 6f 74 68 65 72 20 6f 70 74 69  veral other opti
3650: 6f 6e 73 2c 20 62 75 74 20 77 65 27 76 65 0a 2a  ons, but we've.*
3660: 2a 20 70 61 72 65 64 20 69 74 20 64 6f 77 6e 20  * pared it down 
3670: 74 6f 20 6a 75 73 74 20 74 68 65 73 65 20 74 68  to just these th
3680: 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66 20 6e  ree.).**.** If n
3690: 6f 6e 65 20 6f 66 20 74 68 65 20 61 62 6f 76 65  one of the above
36a0: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
36b0: 65 6e 20 73 65 74 20 53 51 4c 49 54 45 5f 53 59  en set SQLITE_SY
36c0: 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73 0a 2a  STEM_MALLOC as.*
36d0: 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 0a 2a  * the default..*
36e0: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 51  /.#if defined(SQ
36f0: 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c  LITE_SYSTEM_MALL
3700: 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66 69 6e 65  OC) \.  + define
3710: 64 28 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d  d(SQLITE_WIN32_M
3720: 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66  ALLOC) \.  + def
3730: 69 6e 65 64 28 53 51 4c 49 54 45 5f 5a 45 52 4f  ined(SQLITE_ZERO
3740: 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64  _MALLOC) \.  + d
3750: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45  efined(SQLITE_ME
3760: 4d 44 45 42 55 47 29 3e 31 0a 23 20 65 72 72 6f  MDEBUG)>1.# erro
3770: 72 20 22 54 77 6f 20 6f 72 20 6d 6f 72 65 20 6f  r "Two or more o
3780: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
3790: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e  compile-time con
37a0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
37b0: 6e 73 5c 0a 20 61 72 65 20 64 65 66 69 6e 65 64  ns\. are defined
37c0: 20 62 75 74 20 61 74 20 6d 6f 73 74 20 6f 6e 65   but at most one
37d0: 20 69 73 20 61 6c 6c 6f 77 65 64 3a 5c 0a 20 53   is allowed:\. S
37e0: 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c  QLITE_SYSTEM_MAL
37f0: 4c 4f 43 2c 20 53 51 4c 49 54 45 5f 57 49 4e 33  LOC, SQLITE_WIN3
3800: 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 45  2_MALLOC, SQLITE
3810: 5f 4d 45 4d 44 45 42 55 47 2c 5c 0a 20 53 51 4c  _MEMDEBUG,\. SQL
3820: 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 22  ITE_ZERO_MALLOC"
3830: 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69  .#endif.#if defi
3840: 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45  ned(SQLITE_SYSTE
3850: 4d 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20  M_MALLOC) \.  + 
3860: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 57  defined(SQLITE_W
3870: 49 4e 33 32 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20  IN32_MALLOC) \. 
3880: 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54   + defined(SQLIT
3890: 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 29 20 5c  E_ZERO_MALLOC) \
38a0: 0a 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c  .  + defined(SQL
38b0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d 3d 30  ITE_MEMDEBUG)==0
38c0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
38d0: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 31  _SYSTEM_MALLOC 1
38e0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49  .#endif../*.** I
38f0: 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f  f SQLITE_MALLOC_
3900: 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20 6e 6f  SOFT_LIMIT is no
3910: 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 79  t zero, then try
3920: 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a 2a 20   to keep the.** 
3930: 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  sizes of memory 
3940: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65 6c 6f  allocations belo
3950: 77 20 74 68 69 73 20 76 61 6c 75 65 20 77 68 65  w this value whe
3960: 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2f 0a  re possible..*/.
3970: 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c  #if !defined(SQL
3980: 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f  ITE_MALLOC_SOFT_
3990: 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e 65 20  LIMIT).# define 
39a0: 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f  SQLITE_MALLOC_SO
39b0: 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a 23 65  FT_LIMIT 1024.#e
39c0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65 20 6e  ndif../*.** We n
39d0: 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20 5f 58  eed to define _X
39e0: 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73 20 66  OPEN_SOURCE as f
39f0: 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65 72 20  ollows in order 
3a00: 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72 65 63  to enable.** rec
3a10: 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 20 6f  ursive mutexes o
3a20: 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79 73 74  n most Unix syst
3a30: 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20 4f 53  ems.  But Mac OS
3a40: 20 58 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e   X is different.
3a50: 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e 5f 53  .** The _XOPEN_S
3a60: 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63 61 75  OURCE define cau
3a70: 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f 72  ses problems for
3a80: 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61 72 65   Mac OS X we are
3a90: 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69 74 20   told,.** so it 
3aa0: 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 72 65  is omitted there
3ab0: 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
3ac0: 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74 65 72  673..**.** Later
3ad0: 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74 20 5f   we learn that _
3ae0: 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69 73 20  XOPEN_SOURCE is 
3af0: 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f 72 72  poorly or incorr
3b00: 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ectly.** impleme
3b10: 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73 79 73  nted on some sys
3b20: 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61 76 6f  tems.  So we avo
3b30: 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74 20 61  id defining it a
3b40: 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74 20 69  t all.** if it i
3b50: 73 20 61 6c 72 65 61 64 79 20 64 65 66 69 6e 65  s already define
3b60: 64 20 6f 72 20 69 66 20 69 74 20 69 73 20 75 6e  d or if it is un
3b70: 6e 65 65 64 65 64 20 62 65 63 61 75 73 65 20 77  needed because w
3b80: 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64 6f 69  e are.** not doi
3b90: 6e 67 20 61 20 74 68 72 65 61 64 73 61 66 65 20  ng a threadsafe 
3ba0: 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74 20 23  build.  Ticket #
3bb0: 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2681..**.** See 
3bc0: 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32 37 34  also ticket #274
3bd0: 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e  1..*/.#if !defin
3be0: 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45  ed(_XOPEN_SOURCE
3bf0: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 5f  ) && !defined(__
3c00: 44 41 52 57 49 4e 5f 5f 29 20 26 26 20 21 64 65  DARWIN__) && !de
3c10: 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45 5f 5f 29  fined(__APPLE__)
3c20: 20 26 26 20 53 51 4c 49 54 45 5f 54 48 52 45 41   && SQLITE_THREA
3c30: 44 53 41 46 45 0a 23 20 20 64 65 66 69 6e 65 20  DSAFE.#  define 
3c40: 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 35 30  _XOPEN_SOURCE 50
3c50: 30 20 20 2f 2a 20 4e 65 65 64 65 64 20 74 6f 20  0  /* Needed to 
3c60: 65 6e 61 62 6c 65 20 70 74 68 72 65 61 64 20 72  enable pthread r
3c70: 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73  ecursive mutexes
3c80: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a   */.#endif../*.*
3c90: 2a 20 54 68 65 20 54 43 4c 20 68 65 61 64 65 72  * The TCL header
3ca0: 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65 65 64 65  s are only neede
3cb0: 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67  d when compiling
3cc0: 20 74 68 65 20 54 43 4c 20 62 69 6e 64 69 6e 67   the TCL binding
3cd0: 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  s..*/.#if define
3ce0: 64 28 53 51 4c 49 54 45 5f 54 43 4c 29 20 7c 7c  d(SQLITE_TCL) ||
3cf0: 20 64 65 66 69 6e 65 64 28 54 43 4c 53 48 29 0a   defined(TCLSH).
3d00: 23 20 69 6e 63 6c 75 64 65 20 3c 74 63 6c 2e 68  # include <tcl.h
3d10: 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  >.#endif../*.** 
3d20: 4e 44 45 42 55 47 20 61 6e 64 20 53 51 4c 49 54  NDEBUG and SQLIT
3d30: 45 5f 44 45 42 55 47 20 61 72 65 20 6f 70 70 6f  E_DEBUG are oppo
3d40: 73 69 74 65 73 2e 20 20 49 74 20 73 68 6f 75 6c  sites.  It shoul
3d50: 64 20 61 6c 77 61 79 73 20 62 65 20 74 72 75 65  d always be true
3d60: 20 74 68 61 74 0a 2a 2a 20 64 65 66 69 6e 65 64   that.** defined
3d70: 28 4e 44 45 42 55 47 29 3d 3d 21 64 65 66 69 6e  (NDEBUG)==!defin
3d80: 65 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29  ed(SQLITE_DEBUG)
3d90: 2e 20 20 49 66 20 74 68 69 73 20 69 73 20 6e 6f  .  If this is no
3da0: 74 20 63 75 72 72 65 6e 74 6c 79 20 74 72 75 65  t currently true
3db0: 2c 0a 2a 2a 20 6d 61 6b 65 20 69 74 20 74 72 75  ,.** make it tru
3dc0: 65 20 62 79 20 64 65 66 69 6e 69 6e 67 20 6f 72  e by defining or
3dd0: 20 75 6e 64 65 66 69 6e 69 6e 67 20 4e 44 45 42   undefining NDEB
3de0: 55 47 2e 0a 2a 2a 0a 2a 2a 20 53 65 74 74 69 6e  UG..**.** Settin
3df0: 67 20 4e 44 45 42 55 47 20 6d 61 6b 65 73 20 74  g NDEBUG makes t
3e00: 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c 65 72 20  he code smaller 
3e10: 61 6e 64 20 72 75 6e 20 66 61 73 74 65 72 20 62  and run faster b
3e20: 79 20 64 69 73 61 62 6c 69 6e 67 20 74 68 65 0a  y disabling the.
3e30: 2a 2a 20 6e 75 6d 62 65 72 20 61 73 73 65 72 74  ** number assert
3e40: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
3e50: 20 74 68 65 20 63 6f 64 65 2e 20 20 53 6f 20 77   the code.  So w
3e60: 65 20 77 61 6e 74 20 74 68 65 20 64 65 66 61 75  e want the defau
3e70: 6c 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20  lt action.** to 
3e80: 62 65 20 66 6f 72 20 4e 44 45 42 55 47 20 74 6f  be for NDEBUG to
3e90: 20 62 65 20 73 65 74 20 61 6e 64 20 4e 44 45 42   be set and NDEB
3ea0: 55 47 20 74 6f 20 62 65 20 75 6e 64 65 66 69 6e  UG to be undefin
3eb0: 65 64 20 6f 6e 6c 79 20 69 66 20 53 51 4c 49 54  ed only if SQLIT
3ec0: 45 5f 44 45 42 55 47 0a 2a 2a 20 69 73 20 73 65  E_DEBUG.** is se
3ed0: 74 2e 20 20 54 68 75 73 20 4e 44 45 42 55 47 20  t.  Thus NDEBUG 
3ee0: 62 65 63 6f 6d 65 73 20 61 6e 20 6f 70 74 2d 69  becomes an opt-i
3ef0: 6e 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 6e  n rather than an
3f00: 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66 65 61 74   opt-out.** feat
3f10: 75 72 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66  ure..*/.#if !def
3f20: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 26 26 20  ined(NDEBUG) && 
3f30: 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f  !defined(SQLITE_
3f40: 44 45 42 55 47 29 20 0a 23 20 64 65 66 69 6e 65  DEBUG) .# define
3f50: 20 4e 44 45 42 55 47 20 31 0a 23 65 6e 64 69 66   NDEBUG 1.#endif
3f60: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 4e 44 45  .#if defined(NDE
3f70: 42 55 47 29 20 26 26 20 64 65 66 69 6e 65 64 28  BUG) && defined(
3f80: 53 51 4c 49 54 45 5f 44 45 42 55 47 29 0a 23 20  SQLITE_DEBUG).# 
3f90: 75 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 65 6e  undef NDEBUG.#en
3fa0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  dif../*.** The t
3fb0: 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20  estcase() macro 
3fc0: 69 73 20 75 73 65 64 20 74 6f 20 61 69 64 20 69  is used to aid i
3fd0: 6e 20 63 6f 76 65 72 61 67 65 20 74 65 73 74 69  n coverage testi
3fe0: 6e 67 2e 20 20 57 68 65 6e 20 0a 2a 2a 20 64 6f  ng.  When .** do
3ff0: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73  ing coverage tes
4000: 74 69 6e 67 2c 20 74 68 65 20 63 6f 6e 64 69 74  ting, the condit
4010: 69 6f 6e 20 69 6e 73 69 64 65 20 74 68 65 20 61  ion inside the a
4020: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 65  rgument to.** te
4030: 73 74 63 61 73 65 28 29 20 6d 75 73 74 20 62 65  stcase() must be
4040: 20 65 76 61 6c 75 61 74 65 64 20 62 6f 74 68 20   evaluated both 
4050: 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 20 69  true and false i
4060: 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 67 65  n order to.** ge
4070: 74 20 66 75 6c 6c 20 62 72 61 6e 63 68 20 63 6f  t full branch co
4080: 76 65 72 61 67 65 2e 20 20 54 68 65 20 74 65 73  verage.  The tes
4090: 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20 69 73  tcase() macro is
40a0: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 74 6f 20   inserted.** to 
40b0: 68 65 6c 70 20 65 6e 73 75 72 65 20 61 64 65 71  help ensure adeq
40c0: 75 61 74 65 20 74 65 73 74 20 63 6f 76 65 72 61  uate test covera
40d0: 67 65 20 69 6e 20 70 6c 61 63 65 73 20 77 68 65  ge in places whe
40e0: 72 65 20 73 69 6d 70 6c 65 0a 2a 2a 20 63 6f 6e  re simple.** con
40f0: 64 69 74 69 6f 6e 2f 64 65 63 69 73 69 6f 6e 20  dition/decision 
4100: 63 6f 76 65 72 61 67 65 20 69 73 20 69 6e 61 64  coverage is inad
4110: 65 71 75 61 74 65 2e 20 20 46 6f 72 20 65 78 61  equate.  For exa
4120: 6d 70 6c 65 2c 20 74 65 73 74 63 61 73 65 28 29  mple, testcase()
4130: 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
4140: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 62 6f 75  to make sure bou
4150: 6e 64 61 72 79 20 76 61 6c 75 65 73 20 61 72 65  ndary values are
4160: 20 74 65 73 74 65 64 2e 20 20 46 6f 72 0a 2a 2a   tested.  For.**
4170: 20 62 69 74 6d 61 73 6b 20 74 65 73 74 73 2c 20   bitmask tests, 
4180: 74 65 73 74 63 61 73 65 28 29 20 63 61 6e 20 62  testcase() can b
4190: 65 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73  e used to make s
41a0: 75 72 65 20 65 61 63 68 20 62 69 74 0a 2a 2a 20  ure each bit.** 
41b0: 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 61  is significant a
41c0: 6e 64 20 75 73 65 64 20 61 74 20 6c 65 61 73 74  nd used at least
41d0: 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 77 69 74 63   once.  On switc
41e0: 68 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  h statements.** 
41f0: 77 68 65 72 65 20 6d 75 6c 74 69 70 6c 65 20 63  where multiple c
4200: 61 73 65 73 20 67 6f 20 74 6f 20 74 68 65 20 73  ases go to the s
4210: 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20 63 6f 64  ame block of cod
4220: 65 2c 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a  e, testcase().**
4230: 20 63 61 6e 20 69 6e 73 75 72 65 20 74 68 61 74   can insure that
4240: 20 61 6c 6c 20 63 61 73 65 73 20 61 72 65 20 65   all cases are e
4250: 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2f 0a  valuated..**.*/.
4260: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 43 4f  #ifdef SQLITE_CO
4270: 56 45 52 41 47 45 5f 54 45 53 54 0a 53 51 4c 49  VERAGE_TEST.SQLI
4280: 54 45 5f 50 52 49 56 41 54 45 20 20 20 76 6f 69  TE_PRIVATE   voi
4290: 64 20 73 71 6c 69 74 65 33 43 6f 76 65 72 61 67  d sqlite3Coverag
42a0: 65 28 69 6e 74 29 3b 0a 23 20 64 65 66 69 6e 65  e(int);.# define
42b0: 20 74 65 73 74 63 61 73 65 28 58 29 20 20 69 66   testcase(X)  if
42c0: 28 20 58 20 29 7b 20 73 71 6c 69 74 65 33 43 6f  ( X ){ sqlite3Co
42d0: 76 65 72 61 67 65 28 5f 5f 4c 49 4e 45 5f 5f 29  verage(__LINE__)
42e0: 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  ; }.#else.# defi
42f0: 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 0a 23  ne testcase(X).#
4300: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
4310: 20 54 45 53 54 4f 4e 4c 59 20 6d 61 63 72 6f 20   TESTONLY macro 
4320: 69 73 20 75 73 65 64 20 74 6f 20 65 6e 63 6c 6f  is used to enclo
4330: 73 65 20 76 61 72 69 61 62 6c 65 20 64 65 63 6c  se variable decl
4340: 61 72 61 74 69 6f 6e 73 20 6f 72 0a 2a 2a 20 6f  arations or.** o
4350: 74 68 65 72 20 62 69 74 73 20 6f 66 20 63 6f 64  ther bits of cod
4360: 65 20 74 68 61 74 20 61 72 65 20 6e 65 65 64 65  e that are neede
4370: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 74 68 65  d to support the
4380: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 77 69   arguments.** wi
4390: 74 68 69 6e 20 74 65 73 74 63 61 73 65 28 29 20  thin testcase() 
43a0: 61 6e 64 20 61 73 73 65 72 74 28 29 20 6d 61 63  and assert() mac
43b0: 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66  ros..*/.#if !def
43c0: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 7c 7c 20  ined(NDEBUG) || 
43d0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 43  defined(SQLITE_C
43e0: 4f 56 45 52 41 47 45 5f 54 45 53 54 29 0a 23 20  OVERAGE_TEST).# 
43f0: 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28  define TESTONLY(
4400: 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65  X)  X.#else.# de
4410: 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28 58 29  fine TESTONLY(X)
4420: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 53  .#endif../*.** S
4430: 6f 6d 65 74 69 6d 65 73 20 77 65 20 6e 65 65 64  ometimes we need
4440: 20 61 20 73 6d 61 6c 6c 20 61 6d 6f 75 6e 74 20   a small amount 
4450: 6f 66 20 63 6f 64 65 20 73 75 63 68 20 61 73 20  of code such as 
4460: 61 20 76 61 72 69 61 62 6c 65 20 69 6e 69 74 69  a variable initi
4470: 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  alization.** to 
4480: 73 65 74 75 70 20 66 6f 72 20 61 20 6c 61 74 65  setup for a late
4490: 72 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  r assert() state
44a0: 6d 65 6e 74 2e 20 20 57 65 20 64 6f 20 6e 6f 74  ment.  We do not
44b0: 20 77 61 6e 74 20 74 68 69 73 20 63 6f 64 65 20   want this code 
44c0: 74 6f 0a 2a 2a 20 61 70 70 65 61 72 20 77 68 65  to.** appear whe
44d0: 6e 20 61 73 73 65 72 74 28 29 20 69 73 20 64 69  n assert() is di
44e0: 73 61 62 6c 65 64 2e 20 20 54 68 65 20 66 6f 6c  sabled.  The fol
44f0: 6c 6f 77 69 6e 67 20 6d 61 63 72 6f 20 69 73 20  lowing macro is 
4500: 74 68 65 72 65 66 6f 72 65 0a 2a 2a 20 75 73 65  therefore.** use
4510: 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 61  d to contain tha
4520: 74 20 73 65 74 75 70 20 63 6f 64 65 2e 20 20 54  t setup code.  T
4530: 68 65 20 22 56 56 41 22 20 61 63 72 6f 6e 79 6d  he "VVA" acronym
4540: 20 73 74 61 6e 64 73 20 66 6f 72 0a 2a 2a 20 22   stands for.** "
4550: 56 65 72 69 66 69 63 61 74 69 6f 6e 2c 20 56 61  Verification, Va
4560: 6c 69 64 61 74 69 6f 6e 2c 20 61 6e 64 20 41 63  lidation, and Ac
4570: 63 72 65 64 69 74 61 74 69 6f 6e 22 2e 20 20 49  creditation".  I
4580: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
4590: 68 65 0a 2a 2a 20 63 6f 64 65 20 77 69 74 68 69  he.** code withi
45a0: 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 20 77 69 6c  n VVA_ONLY() wil
45b0: 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 75 72 69 6e  l only run durin
45c0: 67 20 76 65 72 69 66 69 63 61 74 69 6f 6e 20 70  g verification p
45d0: 72 6f 63 65 73 73 65 73 2e 0a 2a 2f 0a 23 69 66  rocesses..*/.#if
45e0: 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 20 64 65  ndef NDEBUG.# de
45f0: 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29  fine VVA_ONLY(X)
4600: 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65 66 69    X.#else.# defi
4610: 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29 0a 23  ne VVA_ONLY(X).#
4620: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
4630: 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45   ALWAYS and NEVE
4640: 52 20 6d 61 63 72 6f 73 20 73 75 72 72 6f 75 6e  R macros surroun
4650: 64 20 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73  d boolean expres
4660: 73 69 6f 6e 73 20 77 68 69 63 68 20 0a 2a 2a 20  sions which .** 
4670: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
4680: 61 6c 77 61 79 73 20 62 65 20 74 72 75 65 20 6f  always be true o
4690: 72 20 66 61 6c 73 65 2c 20 72 65 73 70 65 63 74  r false, respect
46a0: 69 76 65 6c 79 2e 20 20 53 75 63 68 0a 2a 2a 20  ively.  Such.** 
46b0: 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 75 6c  expressions coul
46c0: 64 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f  d be omitted fro
46d0: 6d 20 74 68 65 20 63 6f 64 65 20 63 6f 6d 70 6c  m the code compl
46e0: 65 74 65 6c 79 2e 20 20 42 75 74 20 74 68 65 79  etely.  But they
46f0: 0a 2a 2a 20 61 72 65 20 69 6e 63 6c 75 64 65 64  .** are included
4700: 20 69 6e 20 61 20 66 65 77 20 63 61 73 65 73 20   in a few cases 
4710: 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 68 61  in order to enha
4720: 6e 63 65 20 74 68 65 20 72 65 73 69 6c 69 65 6e  nce the resilien
4730: 63 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  ce.** of SQLite 
4740: 74 6f 20 75 6e 65 78 70 65 63 74 65 64 20 62 65  to unexpected be
4750: 68 61 76 69 6f 72 20 2d 20 74 6f 20 6d 61 6b 65  havior - to make
4760: 20 74 68 65 20 63 6f 64 65 20 22 73 65 6c 66 2d   the code "self-
4770: 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 6f 72 20 22  healing".** or "
4780: 64 75 63 74 69 6c 65 22 20 72 61 74 68 65 72 20  ductile" rather 
4790: 74 68 61 6e 20 62 65 69 6e 67 20 22 62 72 69 74  than being "brit
47a0: 74 6c 65 22 20 61 6e 64 20 63 72 61 73 68 69 6e  tle" and crashin
47b0: 67 20 61 74 20 74 68 65 20 66 69 72 73 74 0a 2a  g at the first.*
47c0: 2a 20 68 69 6e 74 20 6f 66 20 75 6e 70 6c 61 6e  * hint of unplan
47d0: 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
47e0: 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
47f0: 64 73 2c 20 41 4c 57 41 59 53 20 61 6e 64 20 4e  ds, ALWAYS and N
4800: 45 56 45 52 20 61 72 65 20 61 64 64 65 64 20 66  EVER are added f
4810: 6f 72 20 64 65 66 65 6e 73 69 76 65 20 63 6f 64  or defensive cod
4820: 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 64 6f  e..**.** When do
4830: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73  ing coverage tes
4840: 74 69 6e 67 20 41 4c 57 41 59 53 20 61 6e 64 20  ting ALWAYS and 
4850: 4e 45 56 45 52 20 61 72 65 20 68 61 72 64 2d 63  NEVER are hard-c
4860: 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 65 20 74 72  oded to.** be tr
4870: 75 65 20 61 6e 64 20 66 61 6c 73 65 20 73 6f 20  ue and false so 
4880: 74 68 61 74 20 74 68 65 20 75 6e 72 65 61 63 68  that the unreach
4890: 61 62 6c 65 20 63 6f 64 65 20 74 68 65 6e 20 73  able code then s
48a0: 70 65 63 69 66 79 20 77 69 6c 6c 0a 2a 2a 20 6e  pecify will.** n
48b0: 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 61 73  ot be counted as
48c0: 20 75 6e 74 65 73 74 65 64 20 63 6f 64 65 2e 0a   untested code..
48d0: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53  */.#if defined(S
48e0: 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54  QLITE_COVERAGE_T
48f0: 45 53 54 29 0a 23 20 64 65 66 69 6e 65 20 41 4c  EST).# define AL
4900: 57 41 59 53 28 58 29 20 20 20 20 20 20 28 31 29  WAYS(X)      (1)
4910: 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 28  .# define NEVER(
4920: 58 29 20 20 20 20 20 20 20 28 30 29 0a 23 65 6c  X)       (0).#el
4930: 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42  if !defined(NDEB
4940: 55 47 29 0a 23 20 64 65 66 69 6e 65 20 41 4c 57  UG).# define ALW
4950: 41 59 53 28 58 29 20 20 20 20 20 20 28 28 58 29  AYS(X)      ((X)
4960: 3f 31 3a 28 61 73 73 65 72 74 28 30 29 2c 30 29  ?1:(assert(0),0)
4970: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52  ).# define NEVER
4980: 28 58 29 20 20 20 20 20 20 20 28 28 58 29 3f 28  (X)       ((X)?(
4990: 61 73 73 65 72 74 28 30 29 2c 31 29 3a 30 29 0a  assert(0),1):0).
49a0: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 41  #else.# define A
49b0: 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28 58  LWAYS(X)      (X
49c0: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52  ).# define NEVER
49d0: 28 58 29 20 20 20 20 20 20 20 28 58 29 0a 23 65  (X)       (X).#e
49e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75  ndif../*.** Retu
49f0: 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  rn true (non-zer
4a00: 6f 29 20 69 66 20 74 68 65 20 69 6e 70 75 74 20  o) if the input 
4a10: 69 73 20 61 20 69 6e 74 65 67 65 72 20 74 68 61  is a integer tha
4a20: 74 20 69 73 20 74 6f 6f 20 6c 61 72 67 65 0a 2a  t is too large.*
4a30: 2a 20 74 6f 20 66 69 74 20 69 6e 20 33 32 2d 62  * to fit in 32-b
4a40: 69 74 73 2e 20 20 54 68 69 73 20 6d 61 63 72 6f  its.  This macro
4a50: 20 69 73 20 75 73 65 64 20 69 6e 73 69 64 65 20   is used inside 
4a60: 6f 66 20 76 61 72 69 6f 75 73 20 74 65 73 74 63  of various testc
4a70: 61 73 65 28 29 0a 2a 2a 20 6d 61 63 72 6f 73 20  ase().** macros 
4a80: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 77  to verify that w
4a90: 65 20 68 61 76 65 20 74 65 73 74 65 64 20 53 51  e have tested SQ
4aa0: 4c 69 74 65 20 66 6f 72 20 6c 61 72 67 65 2d 66  Lite for large-f
4ab0: 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a  ile support..*/.
4ac0: 23 64 65 66 69 6e 65 20 49 53 5f 42 49 47 5f 49  #define IS_BIG_I
4ad0: 4e 54 28 58 29 20 20 28 28 28 58 29 26 7e 28 69  NT(X)  (((X)&~(i
4ae0: 36 34 29 30 78 66 66 66 66 66 66 66 66 29 21 3d  64)0xffffffff)!=
4af0: 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61  0)../*.** The ma
4b00: 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 28 29 20 69  cro unlikely() i
4b10: 73 20 61 20 68 69 6e 74 20 74 68 61 74 20 73 75  s a hint that su
4b20: 72 72 6f 75 6e 64 73 20 61 20 62 6f 6f 6c 65 61  rrounds a boolea
4b30: 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
4b40: 74 68 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20  that is usually 
4b50: 66 61 6c 73 65 2e 20 20 4d 61 63 72 6f 20 6c 69  false.  Macro li
4b60: 6b 65 6c 79 28 29 20 73 75 72 72 6f 75 6e 64 73  kely() surrounds
4b70: 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 65 78  .** a boolean ex
4b80: 70 72 65 73 73 69 6f 6e 20 74 68 61 74 20 69 73  pression that is
4b90: 20 75 73 75 61 6c 6c 79 20 74 72 75 65 2e 20 20   usually true.  
4ba0: 47 43 43 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  GCC is able to.*
4bb0: 2a 20 75 73 65 20 74 68 65 73 65 20 68 69 6e 74  * use these hint
4bc0: 73 20 74 6f 20 67 65 6e 65 72 61 74 65 20 62 65  s to generate be
4bd0: 74 74 65 72 20 63 6f 64 65 2c 20 73 6f 6d 65 74  tter code, somet
4be0: 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66  imes..*/.#if def
4bf0: 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26  ined(__GNUC__) &
4c00: 26 20 30 0a 23 20 64 65 66 69 6e 65 20 6c 69 6b  & 0.# define lik
4c10: 65 6c 79 28 58 29 20 20 20 20 5f 5f 62 75 69 6c  ely(X)    __buil
4c20: 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 31  tin_expect((X),1
4c30: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b  ).# define unlik
4c40: 65 6c 79 28 58 29 20 20 5f 5f 62 75 69 6c 74 69  ely(X)  __builti
4c50: 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 30 29 0a  n_expect((X),0).
4c60: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 6c  #else.# define l
4c70: 69 6b 65 6c 79 28 58 29 20 20 20 20 21 21 28 58  ikely(X)    !!(X
4c80: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b  ).# define unlik
4c90: 65 6c 79 28 58 29 20 20 21 21 28 58 29 0a 23 65  ely(X)  !!(X).#e
4ca0: 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  ndif../*********
4cb0: 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71  ***** Include sq
4cc0: 6c 69 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d  lite3.h in the m
4cd0: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49  iddle of sqliteI
4ce0: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
4cf0: 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****/./*********
4d00: 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65  ***** Begin file
4d10: 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a   sqlite3.h *****
4d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d40: 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31  ****/./*.** 2001
4d50: 20 53 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a   September 15.**
4d60: 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64  .** The author d
4d70: 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67  isclaims copyrig
4d80: 68 74 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63  ht to this sourc
4d90: 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63  e code.  In plac
4da0: 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20  e of.** a legal 
4db0: 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 69 73 20  notice, here is 
4dc0: 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a  a blessing:.**.*
4dd0: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20  *    May you do 
4de0: 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69  good and not evi
4df0: 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  l..**    May you
4e00: 20 66 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73   find forgivenes
4e10: 73 20 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61  s for yourself a
4e20: 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72  nd forgive other
4e30: 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  s..**    May you
4e40: 20 73 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e   share freely, n
4e50: 65 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65  ever taking more
4e60: 20 74 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a   than you give..
4e70: 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **.*************
4e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ea0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4eb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20  ************.** 
4ec0: 54 68 69 73 20 68 65 61 64 65 72 20 66 69 6c 65  This header file
4ed0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
4ee0: 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20  erface that the 
4ef0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a  SQLite library.*
4f00: 2a 20 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c  * presents to cl
4f10: 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20  ient programs.  
4f20: 49 66 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c  If a C-function,
4f30: 20 73 74 72 75 63 74 75 72 65 2c 20 64 61 74 61   structure, data
4f40: 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73  type,.** or cons
4f50: 74 61 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20  tant definition 
4f60: 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
4f70: 69 6e 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68  in this file, th
4f80: 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  en it is.** not 
4f90: 61 20 70 75 62 6c 69 73 68 65 64 20 41 50 49 20  a published API 
4fa0: 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75  of SQLite, is su
4fb0: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
4fc0: 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63  without.** notic
4fd0: 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  e, and should no
4fe0: 74 20 62 65 20 72 65 66 65 72 65 6e 63 65 64 20  t be referenced 
4ff0: 62 79 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74  by programs that
5000: 20 75 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a   use SQLite..**.
5010: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64  ** Some of the d
5020: 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20  efinitions that 
5030: 61 72 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65  are in this file
5040: 20 61 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a   are marked as.*
5050: 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22  * "experimental"
5060: 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20  .  Experimental 
5070: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
5080: 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66  ormally new.** f
5090: 65 61 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79  eatures recently
50a0: 20 61 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65   added to SQLite
50b0: 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74  .  We do not ant
50c0: 69 63 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a  icipate changes.
50d0: 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74  ** to experiment
50e0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 62 75  al interfaces bu
50f0: 74 20 72 65 73 65 72 76 65 20 74 68 65 20 72 69  t reserve the ri
5100: 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  ght to make mino
5110: 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20  r changes.** if 
5120: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
5130: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
5140: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
5150: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
5160: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
5170: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
5180: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
5190: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
51a0: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
51b0: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
51c0: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
51d0: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
51e0: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
51f0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
5200: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
5210: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
5220: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
5230: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
5240: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
5250: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
5260: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
5270: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
5280: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
5290: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
52a0: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
52b0: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
52c0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
52d0: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
52e0: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
52f0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
5300: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
5310: 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  cess..*/.#ifndef
5320: 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65   _SQLITE3_H_.#de
5330: 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f  fine _SQLITE3_H_
5340: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
5350: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
5360: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
5370: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
5380: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
5390: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
53a0: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
53b0: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65   C++..*/.#if 0.e
53c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
53d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  if.../*.** Add t
53e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
53f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a  erride 'extern'.
5400: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
5410: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
5420: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
5430: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23  extern.#endif..#
5440: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50  ifndef SQLITE_AP
5450: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
5460: 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f  E_API.#endif.../
5470: 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70  *.** These no-op
5480: 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64   macros are used
5490: 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74   in front of int
54a0: 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20  erfaces to mark 
54b0: 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  those.** interfa
54c0: 63 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65  ces as either de
54d0: 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65  precated or expe
54e0: 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61  rimental.  New a
54f0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
5500: 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65  hould not use de
5510: 70 72 65 63 61 74 65 64 20 69 6e 74 65 72 66 61  precated interfa
5520: 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 73  ces - they are s
5530: 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77  upport for backw
5540: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
5550: 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70  ility only.  App
5560: 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73  lication writers
5570: 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65   should be aware
5580: 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d   that.** experim
5590: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
55a0: 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20   are subject to 
55b0: 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20  change in point 
55c0: 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
55d0: 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65  These macros use
55e0: 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20  d to resolve to 
55f0: 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66  various kinds of
5600: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
5610: 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65  that.** would ge
5620: 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d  nerate warning m
5630: 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65  essages when the
5640: 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75  y were used.  Bu
5650: 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c  t that.** compil
5660: 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75  er magic ended u
5670: 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63  p generating suc
5680: 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75  h a flurry of bu
5690: 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61  g reports.** tha
56a0: 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20  t we have taken 
56b0: 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67  it all out and g
56c0: 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e  one back to usin
56d0: 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70  g simple.** noop
56e0: 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66   macros..*/.#def
56f0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45  ine SQLITE_DEPRE
5700: 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51  CATED.#define SQ
5710: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
5720: 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20  L../*.** Ensure 
5730: 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65  these symbols we
5740: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
5750: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
5760: 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a  header file..*/.
5770: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
5780: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51  RSION.# undef SQ
5790: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e  LITE_VERSION.#en
57a0: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54  dif.#ifdef SQLIT
57b0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
57c0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
57d0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
57e0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
57f0: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
5800: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
5810: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a  ion Numbers.**.*
5820: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f  * ^(The [SQLITE_
5830: 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72  VERSION] C prepr
5840: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e  ocessor macro in
5850: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68   the sqlite3.h h
5860: 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74  eader.** evaluat
5870: 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c  es to a string l
5880: 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74  iteral that is t
5890: 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  he SQLite versio
58a0: 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  n in the.** form
58b0: 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65  at "X.Y.Z" where
58c0: 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20   X is the major 
58d0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
58e0: 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20  always 3 for.** 
58f0: 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69  SQLite3) and Y i
5900: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73  s the minor vers
5910: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a  ion number and Z
5920: 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20   is the release 
5930: 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54  number.)^.** ^(T
5940: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
5950: 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65  ON_NUMBER] C pre
5960: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
5970: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69  resolves to an i
5980: 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74  nteger.** with t
5990: 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30  he value (X*1000
59a0: 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a  000 + Y*1000 + Z
59b0: 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e  ) where X, Y, an
59c0: 64 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65  d Z are the same
59d0: 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64  .** numbers used
59e0: 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   in [SQLITE_VERS
59f0: 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53  ION].)^.** The S
5a00: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
5a10: 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76  MBER for any giv
5a20: 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  en release of SQ
5a30: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a  Lite will also.*
5a40: 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  * be larger than
5a50: 20 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f   the release fro
5a60: 6d 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65  m which it is de
5a70: 72 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59  rived.  Either Y
5a80: 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64   will.** be held
5a90: 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20   constant and Z 
5aa0: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e  will be incremen
5ab0: 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69  ted or else Y wi
5ac0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
5ad0: 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20  d.** and Z will 
5ae0: 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f  be reset to zero
5af0: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65  ..**.** Since ve
5b00: 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51  rsion 3.6.18, SQ
5b10: 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65  Lite source code
5b20: 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64   has been stored
5b30: 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72   in the.** <a hr
5b40: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66  ef="http://www.f
5b50: 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e  ossil-scm.org/">
5b60: 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61  Fossil configura
5b70: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a  tion management.
5b80: 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20  ** system</a>.  
5b90: 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  ^The SQLITE_SOUR
5ba0: 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c  CE_ID macro eval
5bb0: 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74  uates to.** a st
5bc0: 72 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74  ring which ident
5bd0: 69 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c  ifies a particul
5be0: 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53  ar check-in of S
5bf0: 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20  QLite.** within 
5c00: 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  its configuratio
5c10: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73  n management sys
5c20: 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  tem.  ^The SQLIT
5c30: 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73  E_SOURCE_ID.** s
5c40: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74  tring contains t
5c50: 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  he date and time
5c60: 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e   of the check-in
5c70: 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48   (UTC) and an SH
5c80: 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68  A1.** hash of th
5c90: 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20  e entire source 
5ca0: 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tree..**.** See 
5cb0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c  also: [sqlite3_l
5cc0: 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a  ibversion()],.**
5cd0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
5ce0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20  sion_number()], 
5cf0: 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  [sqlite3_sourcei
5d00: 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
5d10: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
5d20: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
5d30: 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  d()]..*/.#define
5d40: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20   SQLITE_VERSION 
5d50: 20 20 20 20 20 20 20 22 33 2e 37 2e 31 36 22 0a         "3.7.16".
5d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
5d70: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30  ERSION_NUMBER 30
5d80: 30 37 30 31 36 0a 23 64 65 66 69 6e 65 20 53 51  07016.#define SQ
5d90: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
5da0: 20 20 20 20 22 32 30 31 33 2d 30 32 2d 31 35 20      "2013-02-15 
5db0: 30 34 3a 32 31 3a 30 31 20 38 34 33 65 31 63 35  04:21:01 843e1c5
5dc0: 34 33 61 61 62 61 62 38 63 64 36 32 66 32 38 37  43aabab8cd62f287
5dd0: 34 32 64 35 38 31 38 38 38 37 64 33 36 62 63 62  42d5818887d36bcb
5de0: 37 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  7"../*.** CAPI3R
5df0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
5e00: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
5e10: 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  bers.** KEYWORDS
5e20: 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  : sqlite3_versio
5e30: 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  n, sqlite3_sourc
5e40: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
5e50: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
5e60: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
5e70: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
5e80: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
5e90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
5ea0: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
5eb0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
5ec0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
5ed0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
5ee0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
5ef0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
5f00: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
5f10: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
5f20: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
5f30: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
5f40: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
5f50: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
5f60: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
5f70: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
5f80: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
5f90: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
5fa0: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
5fb0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
5fc0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
5fd0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
5fe0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
5ff0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
6000: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
6010: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
6020: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
6030: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
6040: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
6050: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
6060: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
6070: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
6080: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
6090: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
60a0: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
60b0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
60c0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
60d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
60e0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
60f0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
6100: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
6110: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
6120: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
6130: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
6140: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
6150: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
6160: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
6170: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
6180: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
6190: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
61a0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
61b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
61c0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
61d0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
61e0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
61f0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
6200: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
6210: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
6220: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
6230: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
6240: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
6250: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
6260: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
6270: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
6280: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
6290: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
62a0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
62b0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
62c0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
62d0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
62e0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
62f0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
6300: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
6310: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
6320: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
6330: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
6340: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
6350: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
6360: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
6370: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
6380: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
6390: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
63a0: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
63b0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
63c0: 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76  t char sqlite3_v
63d0: 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54  ersion[] = SQLIT
63e0: 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54  E_VERSION;.SQLIT
63f0: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
6400: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
6410: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  sion(void);.SQLI
6420: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
6430: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
6440: 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  eid(void);.SQLIT
6450: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
6460: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
6470: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ber(void);../*.*
6480: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
6490: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d  Time Library Com
64a0: 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  pilation Options
64b0: 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a   Diagnostics.**.
64c0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
64d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
64e0: 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  ed() function re
64f0: 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a  turns 0 or 1 .**
6500: 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74   indicating whet
6510: 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65  her the specifie
6520: 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66  d option was def
6530: 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70  ined at .** comp
6540: 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  ile time.  ^The 
6550: 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d  SQLITE_ prefix m
6560: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72  ay be omitted fr
6570: 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f  om the .** optio
6580: 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f  n name passed to
6590: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
65a0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20  option_used().  
65b0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
65c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
65d0: 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  n_get() function
65e0: 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e   allows iteratin
65f0: 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69  g.** over the li
6600: 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68  st of options th
6610: 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20  at were defined 
6620: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20  at compile time 
6630: 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20  by.** returning 
6640: 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65  the N-th compile
6650: 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72   time option str
6660: 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f  ing.  ^If N is o
6670: 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20  ut of range,.** 
6680: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
6690: 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75  ption_get() retu
66a0: 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
66b0: 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  er.  ^The SQLITE
66c0: 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20  _ .** prefix is 
66d0: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79  omitted from any
66e0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
66f0: 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
6700: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6710: 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70  et()..**.** ^Sup
6720: 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61  port for the dia
6730: 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  gnostic function
6740: 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  s sqlite3_compil
6750: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a  eoption_used().*
6760: 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
6770: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
6780: 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  ) may be omitted
6790: 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74   by specifying t
67a0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
67b0: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f  MIT_COMPILEOPTIO
67c0: 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20  N_DIAGS] option 
67d0: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
67e0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
67f0: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b   SQL functions [
6800: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
6810: 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64  tion_used()] and
6820: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  .** [sqlite_comp
6830: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d  ileoption_get()]
6840: 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c   and the [compil
6850: 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61  e_options pragma
6860: 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  ]..*/.#ifndef SQ
6870: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
6880: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51  EOPTION_DIAGS.SQ
6890: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
68a0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
68b0: 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68  on_used(const ch
68c0: 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53  ar *zOptName);.S
68d0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
68e0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
68f0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
6900: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
6910: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6920: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
6930: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
6940: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
6950: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
6960: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
6970: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
6980: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
6990: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
69a0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
69b0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
69c0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
69d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
69e0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
69f0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
6a00: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
6a10: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
6a20: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
6a30: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
6a40: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
6a50: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
6a60: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
6a70: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
6a80: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
6a90: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
6aa0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
6ab0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
6ac0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
6ad0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
6ae0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
6af0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
6b00: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
6b10: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
6b20: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
6b30: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
6b40: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
6b50: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
6b60: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
6b70: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
6b80: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
6b90: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
6ba0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
6bb0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
6bc0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
6bd0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
6be0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
6bf0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
6c00: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
6c10: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
6c20: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
6c30: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
6c40: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
6c50: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
6c60: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
6c70: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
6c80: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
6c90: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
6ca0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
6cb0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
6cc0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
6cd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
6ce0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
6cf0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
6d00: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
6d10: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
6d20: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
6d30: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
6d40: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
6d50: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
6d60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
6d70: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
6d80: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
6d90: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
6da0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
6db0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
6dc0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
6dd0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
6de0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
6df0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
6e00: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
6e10: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
6e20: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
6e30: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
6e40: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
6e50: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
6e60: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
6e70: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
6e80: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
6e90: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
6ea0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
6eb0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
6ec0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
6ed0: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
6ee0: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
6ef0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
6f00: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
6f10: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
6f20: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
6f30: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
6f40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
6f50: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
6f60: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
6f70: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
6f80: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
6f90: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
6fa0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
6fb0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
6fc0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
6fd0: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
6fe0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
6ff0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
7000: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
7010: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
7020: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
7030: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
7040: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
7050: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
7060: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
7070: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
7080: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7090: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
70a0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
70b0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
70c0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
70d0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
70e0: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
70f0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
7100: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
7110: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
7120: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
7130: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
7140: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
7150: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
7160: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
7170: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
7180: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
7190: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
71a0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
71b0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
71c0: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
71d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
71e0: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
71f0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
7200: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
7210: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
7220: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
7230: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
7240: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
7250: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
7260: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
7270: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
7280: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
7290: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
72a0: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
72b0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
72c0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
72d0: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
72e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
72f0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
7300: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
7310: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
7320: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
7330: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
7340: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
7350: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
7360: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
7370: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
7380: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
7390: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
73a0: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
73b0: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
73c0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
73d0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
73e0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
73f0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
7400: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
7410: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
7420: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
7430: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
7440: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
7450: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
7460: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
7470: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
7480: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
7490: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
74a0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
74b0: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
74c0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
74d0: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
74e0: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
74f0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
7500: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
7510: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
7520: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
7530: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
7540: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
7550: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
7560: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
7570: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
7580: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
7590: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
75a0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
75b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
75c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49  ef unsigned SQLI
75d0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
75e0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
75f0: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
7600: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
7610: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
7620: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
7630: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
7640: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
7650: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
7660: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
7670: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
7680: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
7690: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
76a0: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
76b0: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
76c0: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64  64;.#endif.typed
76d0: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  ef sqlite_int64 
76e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74  sqlite3_int64;.t
76f0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69  ypedef sqlite_ui
7700: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e  nt64 sqlite3_uin
7710: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63  t64;../*.** If c
7720: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70  ompiling for a p
7730: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61  rocessor that la
7740: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  cks floating poi
7750: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73  nt support,.** s
7760: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65  ubstitute intege
7770: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70  r for floating-p
7780: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  oint..*/.#ifdef 
7790: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
77a0: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
77b0: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
77c0: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
77d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
77e0: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
77f0: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
7800: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
7810: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71  3_close() and sq
7820: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
7830: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
7840: 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72  structors.** for
7850: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
7860: 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73  bject..** ^Calls
7870: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   to sqlite3_clos
7880: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
7890: 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72  close_v2() retur
78a0: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 0a 2a  n SQLITE_OK if.*
78b0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  * the [sqlite3] 
78c0: 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73  object is succes
78d0: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64  sfully destroyed
78e0: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61   and all associa
78f0: 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73  ted.** resources
7900: 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64   are deallocated
7910: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
7920: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7930: 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65  ion is associate
7940: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
7950: 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  ed prepared.** s
7960: 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66  tatements or unf
7970: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
7980: 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74  backup objects t
7990: 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  hen sqlite3_clos
79a0: 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76  e().** will leav
79b0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
79c0: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61  onnection open a
79d0: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
79e0: 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20  E_BUSY]..** ^If 
79f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
7a00: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
7a10: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72  h unfinalized pr
7a20: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
7a30: 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69 6e 69 73  s.** and unfinis
7a40: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  hed sqlite3_back
7a50: 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ups, then the da
7a60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7a70: 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20  n becomes.** an 
7a80: 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65  unusable "zombie
7a90: 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74  " which will aut
7aa0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65  omatically be de
7ab0: 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74  allocated when t
7ac0: 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61  he.** last prepa
7ad0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
7ae0: 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68   finalized or th
7af0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62  e last sqlite3_b
7b00: 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69  ackup is.** fini
7b10: 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  shed.  The sqlit
7b20: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e  e3_close_v2() in
7b30: 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e  terface is inten
7b40: 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68  ded for use with
7b50: 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67  .** host languag
7b60: 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62  es that are garb
7b70: 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61  age collected, a
7b80: 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64  nd where the ord
7b90: 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64  er in which.** d
7ba0: 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63  estructors are c
7bb0: 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61  alled is arbitra
7bc0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ry..**.** Applic
7bd0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73  ations should [s
7be0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
7bf0: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
7c00: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
7c10: 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ents],.** [sqlit
7c20: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20  e3_blob_close | 
7c30: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42  close] all [BLOB
7c40: 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a   handles], and .
7c50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
7c60: 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69  up_finish | fini
7c70: 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33  sh] all [sqlite3
7c80: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
7c90: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
7ca0: 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ith the [sqlite3
7cb0: 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74  ] object prior t
7cc0: 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  o attempting to 
7cd0: 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74  close the object
7ce0: 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65  .  ^If.** sqlite
7cf0: 33 5f 63 6c 6f 73 65 28 29 20 69 73 20 63 61 6c  3_close() is cal
7d00: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
7d10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
7d20: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
7d30: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
7d40: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
7d50: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
7d60: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
7d70: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
7d80: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
7d90: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
7da0: 20 62 75 74 20 74 68 65 20 64 65 61 6c 6c 6f 63   but the dealloc
7db0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f  ation.** of reso
7dc0: 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65  urces is deferre
7dd0: 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65  d until all [pre
7de0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
7df0: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
7e00: 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  ],.** and [sqlit
7e10: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
7e20: 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74  ts are also dest
7e30: 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  royed..**.** ^If
7e40: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
7e50: 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65  ject is destroye
7e60: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61  d while a transa
7e70: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a  ction is open,.*
7e80: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  * the transactio
7e90: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  n is automatical
7ea0: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
7eb0: 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61  **.** The C para
7ec0: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
7ed0: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20  3_close(C)] and 
7ee0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
7ef0: 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  2(C)].** must be
7f00: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a   either a NULL.*
7f10: 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20  * pointer or an 
7f20: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
7f30: 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65   pointer obtaine
7f40: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
7f50: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
7f60: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
7f70: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
7f80: 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e  pen_v2()], and n
7f90: 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c  ot previously cl
7fa0: 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  osed..** ^Callin
7fb0: 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  g sqlite3_close(
7fc0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ) or sqlite3_clo
7fd0: 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e  se_v2() with a N
7fe0: 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61  ULL pointer.** a
7ff0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72  rgument is a har
8000: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
8010: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
8020: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c  qlite3_close(sql
8030: 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
8040: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
8050: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
8060: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
8070: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
8080: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
8090: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
80a0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
80b0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
80c0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
80d0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
80e0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
80f0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
8100: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
8110: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
8120: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
8130: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
8140: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
8150: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
8160: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
8170: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8180: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
8190: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
81a0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
81b0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
81c0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
81d0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
81e0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
81f0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
8200: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
8210: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
8220: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
8230: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
8240: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
8250: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
8260: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
8270: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
8280: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
8290: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
82a0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
82b0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
82c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
82d0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
82e0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
82f0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
8300: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8310: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
8320: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
8330: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
8340: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
8350: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
8360: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
8370: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
8380: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
8390: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
83a0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
83b0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
83c0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
83d0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
83e0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
83f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
8400: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
8410: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
8420: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
8430: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
8440: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
8450: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
8460: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
8470: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
8480: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
8490: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
84a0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
84b0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
84c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
84d0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
84e0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
84f0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
8500: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
8510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
8520: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
8530: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
8540: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
8550: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
8560: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
8570: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
8580: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
8590: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
85a0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
85b0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
85c0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
85d0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
85e0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
85f0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
8600: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
8610: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
8620: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
8630: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
8640: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
8650: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
8660: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
8670: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
8680: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
8690: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
86a0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
86b0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
86c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
86d0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
86e0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
86f0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
8700: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
8710: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
8720: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
8730: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
8740: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
8750: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
8760: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
8770: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
8780: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
8790: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
87a0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
87b0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
87c0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
87d0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
87e0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
87f0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
8800: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
8810: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
8820: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
8830: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
8840: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
8850: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
8860: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
8870: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
8880: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
8890: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
88a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
88b0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
88c0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
88d0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
88e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
88f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
8900: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
8910: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
8920: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
8930: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
8940: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
8950: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
8960: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
8970: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
8980: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
8990: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
89a0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
89b0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
89c0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
89d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
89e0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
89f0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
8a00: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
8a10: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
8a20: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
8a30: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
8a40: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
8a50: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
8a60: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
8a70: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
8a80: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
8a90: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
8aa0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
8ab0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
8ac0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
8ad0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
8ae0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
8af0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
8b00: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
8b10: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
8b20: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
8b30: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
8b40: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
8b50: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
8b60: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
8b70: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
8b80: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
8b90: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
8ba0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
8bb0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
8bc0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
8bd0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
8be0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
8bf0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
8c00: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
8c10: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
8c20: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
8c30: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
8c40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8c50: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
8c60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
8c70: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74  t not close [dat
8c80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8c90: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
8ca0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
8cb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
8cc0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
8cd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8ce0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
8cf0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
8d00: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
8d10: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
8d20: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
8d30: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
8d40: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
8d50: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
8d60: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
8d70: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
8d80: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
8d90: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
8da0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
8db0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
8dc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8dd0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
8de0: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
8df0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
8e00: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
8e10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
8e20: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
8e30: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
8e40: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
8e50: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
8e60: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
8e70: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
8e80: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
8e90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8ea0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
8eb0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
8ec0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
8ed0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
8ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8ef0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
8f00: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
8f10: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
8f20: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
8f30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
8f40: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
8f50: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
8f60: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
8f70: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
8f80: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
8f90: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
8fa0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
8fb0: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
8fc0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
8fd0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
8fe0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
8ff0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
9000: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
9010: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
9020: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
9030: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
9040: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
9050: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
9060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
9070: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
9080: 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b  ult codes],.** [
9090: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
90a0: 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51 4c  conflict()] [SQL
90b0: 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
90c0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f  esult codes]..*/
90d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
90e0: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
90f0: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
9100: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
9110: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
9120: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
9130: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
9140: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
9150: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
9160: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
9170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
9180: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
9190: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
91a0: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
91b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
91c0: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
91d0: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
91e0: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
91f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
9200: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
9210: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
9220: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
9230: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
9240: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
9250: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
9260: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
9270: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
9280: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
9290: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
92a0: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
92b0: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
92c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
92d0: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
92e0: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
92f0: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
9300: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
9310: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
9320: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
9330: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
9340: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
9350: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
9360: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
9370: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
9380: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
9390: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
93a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
93b0: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
93c0: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
93d0: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
93e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
93f0: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
9400: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
9410: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
9420: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
9430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
9440: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
9450: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
9460: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
9470: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
9480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
9490: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
94a0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
94b0: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
94c0: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
94d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
94e0: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
94f0: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
9500: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
9520: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
9530: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
9540: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
9550: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
9560: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
9570: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61    16   /* Databa
9580: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23  se is empty */.#
9590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
95a0: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
95b0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
95c0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
95d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
95e0: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
95f0: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
9600: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
9610: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
9620: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
9630: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
9640: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
9650: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
9660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9670: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
9680: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
9690: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
96a0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
96b0: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
96c0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
96d0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
96e0: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
96f0: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
9700: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
9710: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
9720: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
9730: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
9740: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
9750: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
9760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9770: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
9780: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
9790: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
97a0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
97b0: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
97c0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
97d0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
97e0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
97f0: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
9800: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
9810: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
9820: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
9830: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
9840: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
9850: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
9860: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
9870: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
9880: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
9890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
98a0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
98b0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
98c0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
98d0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
98e0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
98f0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
9900: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
9910: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
9920: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
9930: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
9940: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
9950: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
9960: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
9970: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
9980: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
9990: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
99a0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
99b0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
99c0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
99d0: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
99e0: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
99f0: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
9a00: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
9a10: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
9a20: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
9a30: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
9a40: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
9a50: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
9a60: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
9a70: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
9a80: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
9a90: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
9aa0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
9ab0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
9ac0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
9ad0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
9ae0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
9af0: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
9b00: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
9b10: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
9b20: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
9b30: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
9b40: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
9b50: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
9b60: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
9b70: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
9b80: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
9b90: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
9ba0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
9bb0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9bc0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
9bd0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
9be0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
9bf0: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
9c00: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
9c10: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
9c20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
9c30: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
9c40: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
9c50: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
9c60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
9c70: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
9c80: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
9c90: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
9ca0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
9cb0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
9cc0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
9cd0: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
9ce0: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
9cf0: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
9d00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
9d10: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
9d20: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
9d30: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
9d40: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
9d50: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
9d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9d70: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
9d80: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9d90: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
9da0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
9db0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
9dc0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
9dd0: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
9de0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9df0: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
9e00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9e10: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
9e20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9e30: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
9e40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9e50: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
9e60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
9e70: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
9e80: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
9e90: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
9ea0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
9eb0: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
9ec0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
9ed0: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
9ee0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
9ef0: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
9f00: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
9f10: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
9f20: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
9f30: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
9f40: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
9f50: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
9f60: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
9f70: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
9f80: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9f90: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
9fa0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
9fb0: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
9fc0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9fd0: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
9fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
9ff0: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
a000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a010: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
a020: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
a030: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
a040: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a050: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
a060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
a070: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
a080: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a090: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
a0a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
a0b0: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
a0c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a0d0: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
a0e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
a0f0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
a100: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a110: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
a120: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
a130: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
a140: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a150: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
a160: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
a170: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
a180: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a190: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
a1a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a1b0: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
a1c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a1d0: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
a1e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a1f0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
a200: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a210: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
a220: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a230: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
a240: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a250: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
a260: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a270: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
a280: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a290: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
a2a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
a2b0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
a2c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a2d0: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
a2e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
a2f0: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
a300: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a310: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
a320: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
a330: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
a340: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
a350: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
a360: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
a370: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
a380: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
a390: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
a3a0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
a3b0: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
a3c0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
a3d0: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
a3e0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
a3f0: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
a400: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
a410: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
a420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
a430: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
a440: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
a450: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
a460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
a470: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
a480: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
a490: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
a4a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a4b0: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
a4c0: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
a4d0: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
a4e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a4f0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
a500: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
a510: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
a520: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
a530: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
a540: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  CK          (SQL
a550: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c  ITE_ABORT | (2<<
a560: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
a570: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48  TE_CONSTRAINT_CH
a580: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  ECK        (SQLI
a590: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
a5a0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
a5b0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
a5c0: 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28  T_COMMITHOOK   (
a5d0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
a5e0: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
a5f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
a600: 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59  RAINT_FOREIGNKEY
a610: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
a620: 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a  RAINT | (3<<8)).
a630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
a640: 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49  ONSTRAINT_FUNCTI
a650: 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  ON     (SQLITE_C
a660: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c  ONSTRAINT | (4<<
a670: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
a680: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f  TE_CONSTRAINT_NO
a690: 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49  TNULL      (SQLI
a6a0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
a6b0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
a6c0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
a6d0: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28  T_PRIMARYKEY   (
a6e0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
a6f0: 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  T | (6<<8)).#def
a700: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
a710: 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20  RAINT_TRIGGER   
a720: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
a730: 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a  RAINT | (7<<8)).
a740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
a750: 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45  ONSTRAINT_UNIQUE
a760: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
a770: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c  ONSTRAINT | (8<<
a780: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
a790: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54  TE_CONSTRAINT_VT
a7a0: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AB         (SQLI
a7b0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
a7c0: 28 39 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (9<<8))../*.** C
a7d0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
a7e0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
a7f0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
a800: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
a810: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
a820: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
a830: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
a840: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
a850: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
a860: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
a870: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
a880: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
a890: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
a8a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a8b0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
a8c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a8d0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
a8e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a8f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a900: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
a910: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a920: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
a930: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a940: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a950: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
a960: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a970: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
a980: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a990: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a9a0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
a9b0: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
a9c0: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
a9d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a9e0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
a9f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
aa00: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
aa10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
aa20: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
aa30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
aa40: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
aa50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
aa60: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
aa70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
aa80: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
aa90: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
aaa0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
aab0: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
aac0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
aad0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
aae0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
aaf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ab00: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
ab10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
ab20: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
ab30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ab40: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
ab50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
ab60: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
ab70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ab80: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
ab90: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
aba0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
abb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
abc0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
abd0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
abe0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
abf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ac00: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
ac10: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
ac20: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
ac30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ac40: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
ac50: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
ac60: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
ac70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ac80: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
ac90: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
aca0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
acb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
acc0: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
acd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
ace0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
acf0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
ad00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ad10: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
ad20: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
ad30: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
ad40: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
ad50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ad60: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
ad70: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
ad80: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
ad90: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
ada0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
adb0: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
adc0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
add0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
ade0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
adf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ae00: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
ae10: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
ae20: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
ae30: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
ae40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
ae50: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
ae60: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
ae70: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
ae80: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
ae90: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
aea0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
aeb0: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
aec0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
aed0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
aee0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
aef0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
af00: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
af10: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
af20: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
af30: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
af40: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
af50: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
af60: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
af70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
af80: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
af90: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
afa0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
afb0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
afc0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
afd0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
afe0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
aff0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
b000: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
b010: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
b020: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
b030: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
b040: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
b050: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
b060: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
b070: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
b080: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
b090: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
b0a0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
b0b0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
b0c0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
b0d0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
b0e0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
b0f0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
b100: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
b110: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
b120: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
b130: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
b140: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
b150: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
b160: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
b170: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
b180: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
b190: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
b1a0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
b1b0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
b1c0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
b1d0: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
b1e0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
b1f0: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
b200: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
b210: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
b220: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
b230: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
b240: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
b250: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
b260: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
b270: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
b280: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
b290: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
b2a0: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
b2b0: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
b2c0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
b2d0: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
b2e0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
b2f0: 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66  changed..*/.#def
b300: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
b310: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
b320: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
b330: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
b340: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
b350: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
b360: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
b370: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
b380: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
b390: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
b3a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b3b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
b3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
b3d0: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
b3e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
b3f0: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
b400: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
b410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
b420: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
b430: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
b440: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
b450: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
b460: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
b470: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
b480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
b490: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
b4a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
b4b0: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
b4c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
b4d0: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
b4e0: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
b4f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
b500: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
b510: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
b520: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b530: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
b540: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
b550: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
b560: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
b570: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
b580: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
b590: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
b5a0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
b5b0: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
b5c0: 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  001000../*.** CA
b5d0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
b5e0: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
b5f0: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
b600: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
b610: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
b620: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
b630: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
b640: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
b650: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
b660: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
b670: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
b680: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
b690: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
b6a0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
b6b0: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
b6c0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
b6d0: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
b6e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
b6f0: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
b700: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
b710: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
b720: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
b730: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
b740: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
b750: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
b760: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
b770: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
b780: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
b790: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
b7a0: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
b7b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
b7c0: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
b7d0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
b7e0: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
b7f0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
b800: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
b810: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
b820: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
b830: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
b840: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
b850: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
b860: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
b870: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
b880: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
b890: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
b8a0: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
b8b0: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
b8c0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
b8d0: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
b8e0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
b8f0: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
b900: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
b910: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
b920: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
b930: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
b940: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
b950: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
b960: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
b970: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
b980: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
b990: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
b9a0: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
b9b0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
b9c0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
b9d0: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
b9e0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
b9f0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
ba00: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
ba10: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
ba20: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
ba30: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
ba40: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
ba50: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
ba60: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
ba70: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
ba80: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
ba90: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
baa0: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
bab0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
bac0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
bad0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
bae0: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
baf0: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
bb00: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
bb10: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
bb20: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
bb30: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
bb40: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
bb50: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
bb60: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
bb70: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
bb80: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
bb90: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
bba0: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
bbb0: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
bbc0: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
bbd0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
bbe0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
bbf0: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
bc00: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
bc10: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
bc20: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
bc30: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
bc40: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
bc50: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
bc60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
bc70: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
bc80: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
bc90: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
bca0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
bcb0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
bcc0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
bcd0: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
bce0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
bcf0: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
bd00: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
bd10: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
bd20: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
bd30: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
bd40: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
bd50: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
bd60: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
bd70: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
bd80: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
bd90: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
bda0: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
bdb0: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
bdc0: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
bdd0: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
bde0: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
bdf0: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
be00: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
be10: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
be20: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
be30: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
be40: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
be50: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
be60: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
be70: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
be80: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
be90: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
bea0: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
beb0: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
bec0: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
bed0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
bee0: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
bef0: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
bf00: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
bf10: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
bf20: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
bf30: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
bf40: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
bf50: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
bf60: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
bf70: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
bf80: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
bf90: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
bfa0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
bfb0: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
bfc0: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
bfd0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
bfe0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
bff0: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
c000: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
c010: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
c020: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
c030: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
c040: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
c050: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
c060: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
c070: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
c080: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
c090: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
c0a0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
c0b0: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
c0c0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
c0d0: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
c0e0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
c0f0: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
c100: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
c110: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
c120: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
c130: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
c140: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
c150: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
c160: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
c170: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
c180: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
c190: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
c1a0: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
c1b0: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
c1c0: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
c1d0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
c1e0: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
c1f0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
c200: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
c210: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
c220: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
c230: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
c240: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
c250: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
c260: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
c270: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
c280: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
c290: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
c2a0: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
c2b0: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
c2c0: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
c2d0: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
c2e0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
c2f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
c300: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
c310: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
c320: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
c330: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
c340: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
c350: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
c360: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
c370: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
c380: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
c390: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
c3a0: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
c3b0: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
c3c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
c3d0: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
c3e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
c3f0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
c400: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
c410: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
c420: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
c430: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
c440: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
c450: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
c460: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
c470: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
c480: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
c490: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
c4a0: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
c4b0: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
c4c0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
c4d0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
c4e0: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
c4f0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
c500: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
c510: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
c520: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
c530: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
c540: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
c550: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
c560: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
c570: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
c580: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
c590: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
c5a0: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
c5b0: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
c5c0: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
c5d0: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
c5e0: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
c5f0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
c600: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
c610: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
c620: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
c630: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
c640: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
c650: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
c660: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
c670: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
c680: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
c690: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
c6a0: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
c6b0: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
c6c0: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
c6d0: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
c6e0: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
c6f0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
c700: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
c710: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
c720: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
c730: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
c740: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
c750: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
c760: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
c770: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
c780: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
c790: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
c7a0: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
c7b0: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
c7c0: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
c7d0: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
c7e0: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
c7f0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
c800: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
c810: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
c820: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
c830: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
c840: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
c850: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
c860: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
c870: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
c880: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
c890: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
c8a0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
c8b0: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
c8c0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
c8d0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
c8e0: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
c8f0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
c900: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
c910: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
c920: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
c930: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
c940: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
c950: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
c960: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
c970: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
c980: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
c990: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
c9a0: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
c9b0: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
c9c0: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
c9d0: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
c9e0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
c9f0: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
ca00: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
ca10: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
ca20: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
ca30: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
ca40: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
ca50: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
ca60: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
ca70: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
ca80: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
ca90: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
caa0: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
cab0: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
cac0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
cad0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
cae0: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
caf0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
cb00: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
cb10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
cb20: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
cb30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
cb40: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
cb50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
cb60: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
cb70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
cb80: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
cb90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
cba0: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
cbb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
cbc0: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
cbd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
cbe0: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
cbf0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
cc00: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
cc10: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
cc20: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
cc30: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
cc40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
cc50: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
cc60: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
cc70: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
cc80: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
cc90: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
cca0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
ccb0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
ccc0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
ccd0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
cce0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
ccf0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
cd00: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
cd10: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
cd20: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
cd30: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
cd40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
cd50: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
cd60: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
cd70: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
cd80: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
cd90: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
cda0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
cdb0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
cdc0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
cdd0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
cde0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
cdf0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
ce00: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
ce10: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
ce20: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
ce30: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
ce40: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
ce50: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
ce60: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
ce70: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
ce80: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
ce90: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
cea0: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
ceb0: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
cec0: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
ced0: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
cee0: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
cef0: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
cf00: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
cf10: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
cf20: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
cf30: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
cf40: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
cf50: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
cf60: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
cf70: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
cf80: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
cf90: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
cfa0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
cfb0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
cfc0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
cfd0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
cfe0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
cff0: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
d000: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
d010: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
d020: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
d030: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
d040: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
d050: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
d060: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
d070: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
d080: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
d090: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
d0a0: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
d0b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
d0c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
d0d0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
d0e0: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
d0f0: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
d100: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
d110: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
d120: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
d130: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
d140: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
d150: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
d160: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
d170: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
d180: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
d190: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
d1a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
d1b0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
d1c0: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
d1d0: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
d1e0: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
d1f0: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
d200: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
d210: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
d220: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
d230: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
d240: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
d250: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
d260: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
d270: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
d280: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
d290: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
d2a0: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
d2b0: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
d2c0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
d2d0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
d2e0: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
d2f0: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
d300: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
d310: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
d320: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
d330: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
d340: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
d350: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
d360: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
d370: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
d380: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20  rsion 2 */.  /* 
d390: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
d3a0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
d3b0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
d3c0: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
d3d0: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
d3e0: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
d3f0: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
d400: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
d410: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
d420: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
d430: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
d440: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
d450: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
d460: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
d470: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
d480: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
d490: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
d4a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
d4b0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
d4c0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
d4d0: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
d4e0: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
d4f0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
d500: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
d510: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
d520: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
d530: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
d540: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
d550: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
d560: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
d570: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
d580: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
d590: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
d5a0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
d5b0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
d5c0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
d5d0: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
d5e0: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
d5f0: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
d600: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
d610: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
d620: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
d630: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
d640: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
d650: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
d660: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
d670: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
d680: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
d690: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
d6a0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
d6b0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
d6c0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
d6d0: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
d6e0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
d6f0: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
d700: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
d710: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
d720: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
d730: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
d740: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
d750: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
d760: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
d770: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
d780: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
d790: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
d7a0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
d7b0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
d7c0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
d7d0: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
d7e0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
d7f0: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
d800: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
d810: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
d820: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
d830: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
d840: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
d850: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
d860: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
d870: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
d880: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
d890: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
d8a0: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
d8b0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
d8c0: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
d8d0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
d8e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
d8f0: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
d900: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
d910: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
d920: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
d930: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
d940: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
d950: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
d960: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
d970: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
d980: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
d990: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
d9a0: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
d9b0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
d9c0: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
d9d0: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
d9e0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
d9f0: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
da00: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
da10: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
da20: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
da30: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
da40: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
da50: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
da60: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
da70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
da80: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
da90: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
daa0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
dab0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
dac0: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
dad0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
dae0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
daf0: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
db00: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
db10: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
db20: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
db30: 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20  TTED]].** ^(The 
db40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
db50: 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f  NC_OMITTED] opco
db60: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
db70: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a  internally by.**
db80: 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74   SQLite and sent
db90: 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e   to all VFSes in
dba0: 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c   place of a call
dbb0: 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65   to the xSync me
dbc0: 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  thod.** when the
dbd0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
dbe0: 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41  tion has [PRAGMA
dbf0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65   synchronous] se
dc00: 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53  t to OFF.)^.** S
dc10: 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ome specialized 
dc20: 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 20  VFSes need this 
dc30: 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20  signal in order 
dc40: 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65  to operate corre
dc50: 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52  ctly.** when [PR
dc60: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
dc70: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
dc80: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65  onous=OFF] is se
dc90: 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20  t, but most .** 
dca0: 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65  VFSes do not nee
dcb0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e  d this signal an
dcc0: 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  d should silentl
dcd0: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
dce0: 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  code..** Applica
dcf0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
dd00: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
dd10: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
dd20: 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f  ith this.** opco
dd30: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
dd40: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ay disrupt the o
dd50: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
dd60: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
dd70: 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71  s.** that do req
dd80: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
dd90: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
dda0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
ddb0: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
ddc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
ddd0: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
dde0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
ddf0: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
de00: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
de10: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
de20: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
de30: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
de40: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
de50: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
de60: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
de70: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
de80: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
de90: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
dea0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
deb0: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
dec0: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
ded0: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
dee0: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
def0: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
df00: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
df10: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
df20: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
df30: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
df40: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
df50: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
df60: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
df70: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
df80: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
df90: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
dfa0: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
dfb0: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
dfc0: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
dfd0: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
dfe0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
dff0: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
e000: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
e010: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
e020: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
e030: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
e040: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
e050: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
e060: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
e070: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
e080: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
e090: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
e0a0: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
e0b0: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
e0c0: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
e0d0: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
e0e0: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
e0f0: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
e100: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
e110: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
e120: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
e130: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
e140: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
e150: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
e160: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
e170: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
e180: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
e190: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
e1a0: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
e1b0: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
e1c0: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
e1d0: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
e1e0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
e1f0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
e200: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
e210: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
e220: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
e230: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
e240: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
e250: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
e260: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
e270: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
e280: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
e290: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
e2a0: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
e2b0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
e2c0: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
e2d0: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
e2e0: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
e2f0: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
e300: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
e310: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
e320: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
e330: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
e340: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
e350: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
e360: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
e370: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
e380: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
e390: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
e3a0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
e3b0: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
e3c0: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
e3d0: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
e3e0: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
e3f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
e400: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
e410: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
e420: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
e430: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
e440: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
e450: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
e460: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
e470: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
e480: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
e490: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
e4a0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
e4b0: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
e4c0: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
e4d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
e4e0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
e4f0: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
e500: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
e510: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
e520: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
e530: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
e540: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
e550: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
e560: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
e570: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
e580: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
e590: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
e5a0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
e5b0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
e5c0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
e5d0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
e5e0: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
e5f0: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
e600: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
e610: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
e620: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
e630: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
e640: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
e650: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
e660: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
e670: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
e680: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
e690: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
e6a0: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
e6b0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
e6c0: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
e6d0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
e6e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
e6f0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
e700: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
e710: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
e720: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
e730: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
e740: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
e750: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
e760: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
e770: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
e780: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
e790: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
e7a0: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
e7b0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
e7c0: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
e7d0: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
e7e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
e7f0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
e800: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
e810: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
e820: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
e830: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
e840: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
e850: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
e860: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
e870: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
e880: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
e890: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
e8a0: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
e8b0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
e8c0: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
e8d0: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
e8e0: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
e8f0: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
e900: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
e910: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
e920: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
e930: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
e940: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
e950: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
e960: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
e970: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
e980: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
e990: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
e9a0: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
e9b0: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
e9c0: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
e9d0: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
e9e0: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
e9f0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
ea00: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
ea10: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
ea20: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
ea30: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
ea40: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
ea50: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
ea60: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
ea70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
ea80: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
ea90: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
eaa0: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
eab0: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
eac0: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
ead0: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
eae0: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
eaf0: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
eb00: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
eb10: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
eb20: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
eb30: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
eb40: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
eb50: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
eb60: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
eb70: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
eb80: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
eb90: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
eba0: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
ebb0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
ebc0: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
ebd0: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
ebe0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
ebf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ec00: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
ec10: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
ec20: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
ec30: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
ec40: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
ec50: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
ec60: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
ec70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
ec80: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
ec90: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
eca0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
ecb0: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
ecc0: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
ecd0: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
ece0: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
ecf0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
ed00: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
ed10: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
ed20: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
ed30: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
ed40: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
ed50: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
ed60: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
ed70: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
ed80: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
ed90: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
eda0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
edb0: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
edc0: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
edd0: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
ede0: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
edf0: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
ee00: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
ee10: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
ee20: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
ee30: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
ee40: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
ee50: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
ee60: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
ee70: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
ee80: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
ee90: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
eea0: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
eeb0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
eec0: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
eed0: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
eee0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
eef0: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
ef00: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
ef10: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
ef20: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
ef30: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
ef40: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
ef50: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
ef60: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
ef70: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
ef80: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
ef90: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
efa0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
efb0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
efc0: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
efd0: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
efe0: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
eff0: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
f000: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
f010: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
f020: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
f030: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
f040: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
f050: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
f060: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
f070: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
f080: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
f090: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
f0a0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
f0b0: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
f0c0: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
f0d0: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
f0e0: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
f0f0: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
f100: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
f110: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
f120: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
f130: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
f140: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
f150: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
f160: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
f170: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
f180: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
f190: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
f1a0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
f1b0: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
f1c0: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
f1d0: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
f1e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
f1f0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
f200: 5d 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 2d  ].** ^This file-
f210: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
f220: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
f230: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
f240: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
f250: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
f260: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
f270: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
f280: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
f290: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
f2a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
f2b0: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
f2c0: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
f2d0: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
f2e0: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
f2f0: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
f300: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
f310: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
f320: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
f330: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
f340: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
f350: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
f360: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
f370: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
f380: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
f390: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
f3a0: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
f3b0: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
f3c0: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
f3d0: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
f3e0: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
f3f0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
f400: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
f410: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
f420: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
f430: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
f440: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
f450: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
f460: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
f470: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
f480: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
f490: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
f4a0: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
f4b0: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
f4c0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
f4d0: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
f4e0: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
f4f0: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
f500: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
f510: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
f520: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
f530: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
f540: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
f550: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
f560: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
f570: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
f580: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
f590: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
f5a0: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
f5b0: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
f5c0: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
f5d0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
f5e0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
f5f0: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
f600: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
f610: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
f620: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
f630: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
f640: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
f650: 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  *.** </ul>.*/.#d
f660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
f670: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
f680: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
f690: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
f6a0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
f6b0: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
f6c0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
f6d0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
f6e0: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
f6f0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
f700: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
f710: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
f720: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
f730: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
f740: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
f750: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
f760: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
f770: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
f780: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
f790: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
f7a0: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
f7b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
f7c0: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
f7d0: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
f7e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
f7f0: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
f800: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
f810: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
f820: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
f830: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
f840: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
f850: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
f860: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
f870: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
f880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
f890: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
f8a0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
f8b0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
f8c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f8d0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
f8e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
f8f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
f900: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
f910: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
f920: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
f930: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
f940: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 0a 2f             16../
f950: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
f960: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
f970: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
f980: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
f990: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
f9a0: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
f9b0: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
f9c0: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
f9d0: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
f9e0: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
f9f0: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
fa00: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
fa10: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
fa20: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
fa30: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
fa40: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
fa50: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
fa60: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
fa70: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
fa80: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
fa90: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
faa0: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
fab0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
fac0: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
fad0: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
fae0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
faf0: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
fb00: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
fb10: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
fb20: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
fb30: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
fb40: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
fb50: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
fb60: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
fb70: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
fb80: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
fb90: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
fba0: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
fbb0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
fbc0: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
fbd0: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
fbe0: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
fbf0: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
fc00: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
fc10: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
fc20: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
fc30: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
fc40: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
fc50: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
fc60: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
fc70: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
fc80: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
fc90: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
fca0: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
fcb0: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
fcc0: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
fcd0: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
fce0: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
fcf0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
fd00: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
fd10: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
fd20: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
fd30: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
fd40: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
fd50: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
fd60: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
fd70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
fd80: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
fd90: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
fda0: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
fdb0: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
fdc0: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
fdd0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
fde0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
fdf0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
fe00: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
fe10: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
fe20: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
fe30: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
fe40: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
fe50: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
fe60: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
fe70: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
fe80: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
fe90: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
fea0: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
feb0: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
fec0: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
fed0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
fee0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
fef0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
ff00: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
ff10: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
ff20: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
ff30: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
ff40: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
ff50: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
ff60: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
ff70: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
ff80: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
ff90: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
ffa0: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
ffb0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
ffc0: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
ffd0: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
ffe0: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
fff0: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
10000 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
10010 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
10020 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
10030 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
10040 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
10050 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
10060 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
10070 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
10080 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
10090 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
100a0 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
100b0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
100c0 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
100d0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
100e0 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
100f0 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
10100 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
10110 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
10120 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
10130 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
10140 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
10150 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
10160 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
10170 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
10180 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
10190 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
101a0 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
101b0 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
101c0 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
101d0 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
101e0 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
101f0 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
10200 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
10210 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
10220 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
10230 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
10240 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
10250 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
10260 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
10270 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
10280 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
10290 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
102a0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
102b0 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
102c0 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
102d0 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
102e0 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
102f0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
10300 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
10310 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
10320 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
10330 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
10340 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
10350 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
10360 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
10370 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
10380 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
10390 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
103a0 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
103b0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
103c0 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
103d0 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
103e0 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
103f0 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
10400 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
10410 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
10420 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
10430 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
10440 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
10450 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
10460 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
10470 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
10480 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
10490 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
104a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
104b0 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
104c0 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
104d0 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
104e0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
104f0 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
10500 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
10510 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
10520 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
10530 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
10540 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
10550 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
10560 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
10570 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
10580 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
10590 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
105a0 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
105b0 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
105c0 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
105d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
105e0 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
105f0 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
10600 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
10610 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
10620 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
10630 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
10640 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
10650 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
10660 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
10670 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
10680 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
10690 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
106a0 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
106b0 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
106c0 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
106d0 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
106e0 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
106f0 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
10700 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
10710 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
10720 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
10730 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
10740 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
10750 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
10760 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
10770 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
10780 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
10790 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
107a0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
107b0 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
107c0 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
107d0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
107e0 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
107f0 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
10800 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
10810 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
10820 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
10830 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
10840 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
10850 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
10860 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
10870 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
10880 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
10890 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
108a0 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
108b0 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
108c0 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
108d0 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
108e0 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
108f0 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
10900 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
10910 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
10920 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
10930 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
10940 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
10950 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
10960 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
10970 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
10980 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
10990 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
109a0 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
109b0 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
109c0 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
109d0 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
109e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
109f0 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
10a00 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
10a10 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
10a20 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
10a30 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
10a40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
10a50 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
10a60 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
10a70 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
10a80 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
10a90 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
10aa0 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
10ab0 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
10ac0 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
10ad0 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
10ae0 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
10af0 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
10b00 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
10b10 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
10b20 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
10b30 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
10b40 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
10b50 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
10b60 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
10b70 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
10b80 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
10b90 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
10ba0 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
10bb0 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
10bc0 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
10bd0 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
10be0 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
10bf0 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
10c00 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
10c10 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
10c20 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
10c30 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
10c40 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
10c50 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
10c60 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
10c70 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
10c80 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
10c90 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
10ca0 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
10cb0 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
10cc0 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
10cd0 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
10ce0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
10cf0 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
10d00 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
10d10 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
10d20 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
10d30 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
10d40 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
10d50 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
10d60 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
10d70 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
10d80 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
10d90 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
10da0 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
10db0 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
10dc0 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
10dd0 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
10de0 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
10df0 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
10e00 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
10e10 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
10e20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
10e30 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
10e40 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
10e50 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
10e60 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
10e70 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
10e80 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
10e90 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
10ea0 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
10eb0 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
10ec0 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
10ed0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
10ee0 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
10ef0 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
10f00 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
10f10 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
10f20 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
10f30 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
10f40 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
10f50 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
10f60 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
10f70 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
10f80 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
10f90 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
10fa0 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
10fb0 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
10fc0 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
10fd0 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
10fe0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
10ff0 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
11000 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
11010 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
11020 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
11030 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
11040 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
11050 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
11060 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
11070 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
11080 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
11090 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
110a0 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
110b0 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
110c0 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
110d0 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
110e0 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
110f0 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
11100 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
11110 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
11120 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
11130 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
11140 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
11150 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
11160 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
11170 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
11180 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
11190 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
111a0 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
111b0 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
111c0 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
111d0 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
111e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
111f0 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
11200 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
11210 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
11220 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
11230 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
11240 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
11250 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
11260 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
11270 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
11280 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
11290 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
112a0 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
112b0 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
112c0 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
112d0 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
112e0 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
112f0 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
11300 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
11310 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
11320 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
11330 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
11340 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
11350 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
11360 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
11370 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
11380 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
11390 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
113a0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
113b0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
113c0 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
113d0 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
113e0 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
113f0 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
11400 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
11410 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
11420 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
11430 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
11440 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
11450 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
11460 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
11470 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
11480 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
11490 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
114a0 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
114b0 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
114c0 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
114d0 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
114e0 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
114f0 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
11500 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
11510 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
11520 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
11530 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
11540 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
11550 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
11560 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
11570 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
11580 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
11590 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
115a0 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
115b0 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
115c0 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
115d0 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
115e0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
115f0 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
11600 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
11610 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
11620 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
11630 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
11640 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
11650 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
11660 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
11670 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
11680 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
11690 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
116a0 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
116b0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
116c0 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
116d0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
116e0 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
116f0 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
11700 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
11710 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
11720 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
11730 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
11740 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
11750 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
11760 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
11770 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
11780 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
11790 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
117a0 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
117b0 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
117c0 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
117d0 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
117e0 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
117f0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
11800 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
11810 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
11820 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
11830 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
11840 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
11850 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
11860 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
11870 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
11880 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
11890 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
118a0 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
118b0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
118c0 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
118d0 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
118e0 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
118f0 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
11900 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
11910 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
11920 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
11930 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
11940 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
11950 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
11960 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
11970 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
11980 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
11990 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
119a0 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
119b0 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
119c0 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
119d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
119e0 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
119f0 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
11a00 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
11a10 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
11a20 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
11a30 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
11a40 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
11a50 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
11a60 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
11a70 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
11a80 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
11a90 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
11aa0 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
11ab0 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
11ac0 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
11ad0 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
11ae0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
11af0 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
11b00 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
11b10 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
11b20 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
11b30 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
11b40 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
11b50 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
11b60 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
11b70 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
11b80 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
11b90 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
11ba0 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
11bb0 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
11bc0 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
11bd0 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
11be0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
11bf0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
11c00 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
11c10 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
11c20 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
11c30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
11c40 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
11c50 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
11c60 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
11c70 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
11c80 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
11c90 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
11ca0 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
11cb0 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
11cc0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
11cd0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
11ce0 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
11cf0 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
11d00 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
11d10 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
11d20 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
11d30 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
11d40 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
11d50 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
11d60 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
11d70 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
11d80 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
11d90 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
11da0 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
11db0 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
11dc0 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
11dd0 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
11de0 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
11df0 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
11e00 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
11e10 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
11e20 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
11e30 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
11e40 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
11e50 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
11e60 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
11e70 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
11e80 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
11e90 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
11ea0 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
11eb0 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
11ec0 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
11ed0 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
11ee0 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
11ef0 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
11f00 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
11f10 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
11f20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
11f30 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
11f40 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
11f50 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
11f60 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
11f70 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
11f80 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
11f90 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
11fa0 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
11fb0 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
11fc0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
11fd0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
11fe0 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
11ff0 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
12000 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
12010 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
12020 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
12030 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
12040 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
12050 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
12060 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
12070 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
12080 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
12090 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
120a0 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
120b0 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
120c0 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
120d0 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
120e0 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
120f0 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
12100 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
12110 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
12120 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
12130 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
12140 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
12150 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12160 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
12170 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
12180 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
12190 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
121a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
121b0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
121c0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
121d0 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
121e0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
121f0 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
12200 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
12210 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
12220 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
12230 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
12240 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
12250 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
12260 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
12270 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
12280 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
12290 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
122a0 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
122b0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
122c0 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
122d0 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
122e0 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
122f0 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
12300 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
12310 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
12320 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
12330 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
12340 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
12350 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
12360 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
12370 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
12380 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
12390 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
123a0 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
123b0 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
123c0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
123d0 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
123e0 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
123f0 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
12400 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
12410 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
12420 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
12430 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
12440 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
12450 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
12460 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
12470 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
12480 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
12490 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
124a0 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
124b0 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
124c0 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
124d0 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
124e0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
124f0 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
12500 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
12510 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
12520 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
12530 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
12540 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
12550 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
12560 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
12570 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
12580 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
12590 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
125a0 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
125b0 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
125c0 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
125d0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
125e0 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
125f0 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
12600 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
12610 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
12620 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
12630 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
12640 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
12650 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
12660 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
12670 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
12680 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
12690 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
126a0 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
126b0 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
126c0 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
126d0 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
126e0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
126f0 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
12700 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
12710 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
12720 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
12730 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
12740 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
12750 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
12760 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
12770 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
12780 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
12790 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
127a0 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
127b0 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
127c0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
127d0 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
127e0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
127f0 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
12800 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
12810 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
12820 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
12830 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
12840 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
12850 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
12860 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
12870 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
12880 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
12890 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
128a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
128b0 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
128c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
128d0 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
128e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
128f0 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
12900 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
12910 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
12920 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
12930 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
12940 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
12950 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
12960 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
12970 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
12980 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
12990 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
129a0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
129b0 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
129c0 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
129d0 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
129e0 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
129f0 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
12a00 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
12a10 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
12a20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
12a30 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
12a40 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
12a50 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
12a60 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
12a70 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
12a80 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
12a90 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
12aa0 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
12ab0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
12ac0 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
12ad0 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
12ae0 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
12af0 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
12b00 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
12b10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
12b20 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
12b30 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
12b40 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
12b50 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
12b60 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
12b70 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
12b80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
12b90 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
12ba0 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
12bb0 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
12bc0 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
12bd0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
12be0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
12bf0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
12c00 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
12c10 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
12c20 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
12c30 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12c40 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
12c50 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
12c60 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
12c70 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
12c80 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
12c90 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12ca0 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
12cb0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
12cc0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
12cd0 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
12ce0 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
12cf0 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
12d00 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12d10 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
12d20 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
12d30 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
12d40 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
12d50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
12d60 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
12d70 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
12d80 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
12d90 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
12da0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
12db0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
12dc0 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
12dd0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12de0 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
12df0 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
12e00 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
12e10 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
12e20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
12e30 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
12e40 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
12e50 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12e60 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
12e70 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
12e80 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
12e90 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
12ea0 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
12eb0 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
12ec0 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
12ed0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
12ee0 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
12ef0 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
12f00 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
12f10 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
12f20 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
12f30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12f40 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
12f50 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
12f60 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
12f70 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
12f80 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
12f90 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
12fa0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
12fb0 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
12fc0 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
12fd0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12fe0 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
12ff0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
13000 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
13010 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
13020 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
13030 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
13040 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
13050 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
13060 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
13070 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
13080 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
13090 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
130a0 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
130b0 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
130c0 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
130d0 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
130e0 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
130f0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
13100 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
13110 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
13120 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
13130 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
13140 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
13150 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
13160 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
13170 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
13180 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
13190 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
131a0 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
131b0 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
131c0 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
131d0 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
131e0 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
131f0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
13200 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
13210 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
13220 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
13230 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
13240 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
13250 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
13260 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
13270 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
13280 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
13290 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
132a0 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
132b0 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
132c0 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
132d0 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
132e0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
132f0 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
13300 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
13310 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
13320 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
13330 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
13340 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
13350 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
13360 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
13370 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13380 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
13390 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
133a0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
133b0 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
133c0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
133d0 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
133e0 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
133f0 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
13400 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
13410 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
13420 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
13430 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
13440 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
13450 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
13460 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
13470 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
13480 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
13490 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
134a0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
134b0 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
134c0 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
134d0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
134e0 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
134f0 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
13500 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
13510 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
13520 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
13530 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
13540 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
13550 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
13560 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
13570 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
13580 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
13590 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
135a0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
135b0 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
135c0 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
135d0 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
135e0 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
135f0 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
13600 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
13610 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
13620 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
13630 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
13640 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
13650 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
13660 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
13670 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
13680 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
13690 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
136a0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
136b0 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
136c0 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
136d0 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
136e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
136f0 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
13700 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
13710 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
13720 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
13730 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
13740 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
13750 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
13760 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
13770 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
13780 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
13790 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
137a0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
137b0 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
137c0 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
137d0 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
137e0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
137f0 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
13800 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
13810 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
13820 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
13830 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
13840 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
13850 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
13860 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
13870 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
13880 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
13890 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
138a0 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
138b0 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
138c0 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
138d0 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
138e0 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
138f0 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
13900 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
13910 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
13920 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
13930 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
13940 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
13950 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
13960 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
13970 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
13980 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
13990 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
139a0 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
139b0 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
139c0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
139d0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
139e0 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
139f0 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
13a00 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
13a10 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
13a20 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
13a30 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
13a40 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
13a50 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
13a60 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
13a70 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ze(void);.SQLITE
13a80 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
13a90 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
13aa0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
13ab0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
13ac0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
13ad0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  I int sqlite3_os
13ae0 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
13af0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
13b00 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
13b10 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
13b20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
13b30 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
13b40 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
13b50 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
13b60 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
13b70 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
13b80 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
13b90 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
13ba0 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
13bb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
13bc0 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
13bd0 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
13be0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
13bf0 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
13c00 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
13c10 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
13c20 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
13c30 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
13c40 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
13c50 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
13c60 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
13c70 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
13c80 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
13c90 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
13ca0 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
13cb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
13cc0 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
13cd0 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
13ce0 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
13cf0 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
13d00 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
13d10 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
13d20 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
13d30 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
13d40 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
13d50 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
13d60 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
13d70 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
13d80 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
13d90 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
13da0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
13db0 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
13dc0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
13dd0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
13de0 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
13df0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
13e00 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
13e10 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
13e20 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
13e30 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
13e40 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
13e50 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
13e60 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
13e70 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
13e80 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
13e90 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
13ea0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
13eb0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
13ec0 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
13ed0 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
13ee0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
13ef0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
13f00 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
13f10 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
13f20 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13f30 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
13f40 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
13f50 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
13f60 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
13f70 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
13f80 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
13f90 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
13fa0 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
13fb0 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
13fc0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13fd0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
13fe0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13ff0 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
14000 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
14010 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
14020 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
14030 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
14040 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
14050 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
14060 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
14070 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
14080 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
14090 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53  rror code]..*/.S
140a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
140b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
140c0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
140d0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
140e0 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
140f0 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  ections.**.** Th
14100 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
14110 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
14120 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
14130 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
14140 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
14150 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14160 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
14170 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
14180 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
14190 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
141a0 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
141b0 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
141c0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
141d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
141e0 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
141f0 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
14200 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
14210 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
14220 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
14230 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
14240 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
14250 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
14260 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
14270 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
14280 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
14290 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
142a0 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
142b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
142c0 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
142d0 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
142e0 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
142f0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
14300 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
14310 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
14320 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
14330 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
14340 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
14350 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
14360 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
14370 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
14380 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
14390 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
143a0 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
143b0 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
143c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
143d0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
143e0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
143f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14400 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
14410 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
14420 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
14430 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
14440 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14450 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
14460 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
14470 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
14480 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
14490 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
144a0 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
144b0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
144c0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
144d0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
144e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
144f0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
14500 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14510 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
14520 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
14530 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
14540 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
14550 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
14560 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14570 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
14580 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
14590 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
145a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
145b0 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
145c0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
145d0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
145e0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
145f0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
14600 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14610 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
14620 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
14630 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
14640 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
14650 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
14660 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
14670 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
14680 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
14690 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
146a0 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
146b0 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
146c0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
146d0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
146e0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
146f0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
14700 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
14710 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
14720 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
14730 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
14740 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
14750 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
14760 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
14770 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
14780 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
14790 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
147a0 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
147b0 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
147c0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
147d0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
147e0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
147f0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
14800 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
14810 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
14820 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
14830 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
14840 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
14850 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
14860 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
14870 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
14880 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
14890 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
148a0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
148b0 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
148c0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
148d0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
148e0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
148f0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
14900 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
14910 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
14920 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
14930 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
14940 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
14950 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
14960 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
14970 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
14980 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
14990 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
149a0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
149b0 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
149c0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
149d0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
149e0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
149f0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
14a00 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
14a10 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
14a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
14a30 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
14a40 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
14a50 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
14a60 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
14a70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
14a80 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
14a90 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
14aa0 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
14ab0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
14ac0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
14ad0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
14ae0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
14af0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
14b00 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
14b10 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
14b20 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
14b30 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
14b40 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
14b50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
14b60 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
14b70 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
14b80 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
14b90 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
14ba0 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
14bb0 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
14bc0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
14bd0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
14be0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
14bf0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
14c00 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
14c10 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
14c20 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
14c30 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
14c40 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
14c50 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
14c60 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
14c70 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
14c80 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
14c90 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
14ca0 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
14cb0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
14cc0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
14cd0 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
14ce0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
14cf0 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
14d00 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
14d10 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
14d20 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
14d30 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
14d40 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
14d50 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
14d60 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
14d70 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
14d80 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
14d90 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
14da0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
14db0 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
14dc0 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
14dd0 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
14de0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
14df0 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
14e00 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
14e10 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
14e20 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
14e30 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
14e40 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
14e50 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
14e60 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
14e70 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
14e80 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
14e90 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
14ea0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
14eb0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
14ec0 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
14ed0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
14ee0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
14ef0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
14f00 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
14f10 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
14f20 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
14f30 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
14f40 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
14f50 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
14f60 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
14f70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14f80 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
14f90 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
14fa0 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
14fb0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
14fc0 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
14fd0 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
14fe0 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
14ff0 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
15000 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
15010 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
15020 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
15030 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
15040 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
15050 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
15060 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
15070 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
15080 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
15090 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
150a0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
150b0 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
150c0 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
150d0 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
150e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
150f0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
15100 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
15110 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
15120 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
15130 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
15140 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
15150 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
15160 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
15170 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
15180 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
15190 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
151a0 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
151b0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
151c0 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
151d0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
151e0 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
151f0 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
15200 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
15210 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
15220 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
15230 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
15240 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
15250 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
15260 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
15270 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
15280 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
15290 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
152a0 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
152b0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
152c0 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
152d0 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
152e0 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
152f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
15300 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
15310 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
15320 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
15330 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
15340 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
15350 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
15360 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
15370 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
15380 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
15390 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
153a0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
153b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
153c0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
153d0 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
153e0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
153f0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
15400 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
15410 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
15420 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
15430 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
15440 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
15450 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
15460 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
15470 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
15480 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
15490 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
154a0 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
154b0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
154c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
154d0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
154e0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
154f0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
15500 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
15510 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
15520 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
15530 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
15540 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
15550 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
15560 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
15570 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
15580 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
15590 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
155a0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
155b0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
155c0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
155d0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
155e0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
155f0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
15600 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
15610 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
15620 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
15630 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
15640 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
15650 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
15660 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
15670 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
15680 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
15690 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
156a0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
156b0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
156c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
156d0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
156e0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
156f0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
15700 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
15710 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
15720 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
15730 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
15740 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
15750 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
15760 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
15770 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
15780 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
15790 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
157a0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
157b0 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
157c0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
157d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
157e0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
157f0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
15800 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
15810 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
15820 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
15830 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
15840 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
15850 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
15860 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
15870 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
15880 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
15890 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
158a0 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
158b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
158c0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
158d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
158e0 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
158f0 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
15900 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
15910 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
15920 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
15930 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
15940 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
15950 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
15960 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
15970 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
15980 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
15990 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
159a0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
159b0 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
159c0 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
159d0 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
159e0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
159f0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
15a00 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
15a10 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
15a20 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
15a30 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
15a40 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15a50 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
15a60 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
15a70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
15a80 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
15a90 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
15aa0 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
15ab0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
15ac0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
15ad0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
15ae0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
15af0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
15b00 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
15b10 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
15b20 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
15b30 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
15b40 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15b50 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
15b60 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
15b70 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
15b80 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
15b90 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
15ba0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
15bb0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
15bc0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
15bd0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
15be0 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
15bf0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
15c00 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
15c10 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
15c20 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
15c30 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
15c40 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
15c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
15c60 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
15c70 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
15c80 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
15c90 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
15ca0 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
15cb0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
15cc0 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
15cd0 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
15ce0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
15cf0 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
15d00 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
15d10 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
15d20 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
15d30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
15d40 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
15d50 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
15d60 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
15d70 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
15d80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
15d90 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
15da0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
15db0 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
15dc0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
15dd0 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
15de0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
15df0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
15e00 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
15e10 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
15e20 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
15e30 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
15e40 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
15e50 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
15e60 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
15e70 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
15e80 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
15e90 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
15ea0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
15eb0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
15ec0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
15ed0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
15ee0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
15ef0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
15f00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15f10 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
15f20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
15f30 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
15f40 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
15f50 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15f60 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15f70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15f80 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
15f90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
15fa0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15fb0 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
15fc0 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
15fd0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
15fe0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
15ff0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
16000 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
16010 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
16020 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16030 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
16040 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
16050 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
16060 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
16070 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
16080 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
16090 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
160a0 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
160b0 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
160c0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
160d0 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
160e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
160f0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
16100 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16110 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
16120 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
16130 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
16140 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
16150 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
16160 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
16170 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
16180 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
16190 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
161a0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
161b0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
161c0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
161d0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
161e0 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
161f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
16200 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
16210 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
16220 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
16230 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
16240 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
16250 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
16260 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
16270 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
16280 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
16290 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
162a0 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
162b0 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
162c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
162d0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
162e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
162f0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
16300 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
16310 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
16320 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
16330 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
16340 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
16350 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
16360 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
16370 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
16380 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
16390 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
163a0 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
163b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
163c0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
163d0 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a  disabled, the .*
163e0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
163f0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
16400 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
16410 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
16420 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
16430 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
16440 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
16450 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
16460 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
16470 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
16480 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
16490 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
164a0 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
164b0 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
164c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
164d0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
164e0 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
164f0 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
16500 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
16510 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
16520 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
16530 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
16540 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
16550 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
16560 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
16570 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
16580 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16590 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
165a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
165b0 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
165c0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
165d0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
165e0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
165f0 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
16600 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
16610 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
16620 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
16630 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
16640 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
16650 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
16660 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
16670 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
16680 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
16690 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
166a0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
166b0 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
166c0 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
166d0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
166e0 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
166f0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
16700 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
16710 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
16720 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
16730 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
16740 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
16750 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
16760 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
16770 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
16780 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
16790 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
167a0 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
167b0 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
167c0 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
167d0 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
167e0 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
167f0 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
16800 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
16810 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
16820 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
16830 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
16840 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
16850 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
16860 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
16870 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
16880 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
16890 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
168a0 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
168b0 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
168c0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
168d0 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
168e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
168f0 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
16900 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
16910 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
16920 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
16930 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
16940 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16950 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
16960 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
16970 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
16980 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16990 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
169a0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
169b0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
169c0 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
169d0 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
169e0 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
169f0 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
16a00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
16a10 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
16a20 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
16a30 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
16a40 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
16a50 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
16a60 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
16a70 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
16a80 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
16a90 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
16aa0 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
16ab0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
16ac0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
16ad0 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
16ae0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
16af0 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
16b00 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
16b10 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
16b20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
16b30 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
16b40 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
16b50 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
16b60 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
16b70 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
16b80 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
16b90 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
16ba0 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
16bb0 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
16bc0 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
16bd0 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
16be0 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
16bf0 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
16c00 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
16c10 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
16c20 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
16c30 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
16c40 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
16c50 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
16c60 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
16c70 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
16c80 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
16c90 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
16ca0 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
16cb0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
16cc0 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
16cd0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
16ce0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
16cf0 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
16d00 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
16d10 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
16d20 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
16d30 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
16d40 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
16d50 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
16d60 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
16d70 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
16d80 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
16d90 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
16da0 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
16db0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
16dc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
16dd0 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
16de0 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
16df0 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
16e00 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
16e10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
16e20 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
16e30 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
16e40 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
16e50 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
16e60 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
16e70 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
16e80 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16e90 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
16ea0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16eb0 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
16ec0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16ed0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
16ee0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
16ef0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
16f00 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
16f10 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
16f20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16f30 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
16f40 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
16f50 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
16f60 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
16f70 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
16f80 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
16f90 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
16fa0 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
16fb0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
16fc0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
16fd0 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
16fe0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
16ff0 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
17000 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
17010 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
17020 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
17030 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
17040 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
17050 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
17060 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
17070 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
17080 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
17090 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
170a0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
170b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
170c0 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
170d0 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
170e0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
170f0 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
17100 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
17110 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
17120 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
17130 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
17140 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
17150 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
17160 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
17170 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
17180 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
17190 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
171a0 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
171b0 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
171c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
171d0 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
171e0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
171f0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
17200 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
17210 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
17220 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
17230 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
17240 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
17250 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
17260 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
17270 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
17280 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
17290 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
172a0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
172b0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
172c0 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
172d0 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
172e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
172f0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
17300 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17310 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
17320 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
17330 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17340 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
17350 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
17360 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
17370 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
17380 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
17390 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
173a0 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
173b0 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
173c0 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
173d0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
173e0 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
173f0 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
17400 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
17410 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
17420 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
17430 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
17440 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
17450 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
17460 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
17470 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
17480 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
17490 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
174a0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
174b0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
174c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
174d0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
174e0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
174f0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
17500 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
17510 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
17520 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
17530 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
17540 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
17550 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
17560 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
17570 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
17580 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17590 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
175a0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
175b0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
175c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
175d0 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
175e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
175f0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
17600 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
17610 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17620 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
17630 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
17640 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
17650 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
17660 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
17670 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
17680 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
17690 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
176a0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
176b0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
176c0 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
176d0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
176e0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
176f0 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
17700 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
17710 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
17720 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
17730 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
17740 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
17750 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
17760 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
17770 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
17780 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
17790 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
177a0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
177b0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
177c0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
177d0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
177e0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
177f0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
17800 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
17810 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
17820 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
17830 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
17840 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
17850 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
17860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
17870 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
17880 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
17890 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
178a0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
178b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
178c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
178d0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
178e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
178f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
17900 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
17910 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
17920 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
17930 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
17940 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
17950 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
17960 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
17970 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
17980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17990 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
179a0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
179b0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
179c0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
179d0 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
179e0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
179f0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
17a00 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
17a10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17a20 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
17a30 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
17a40 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
17a50 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
17a60 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
17a70 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
17a80 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
17a90 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17aa0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
17ab0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
17ac0 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
17ad0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
17ae0 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
17af0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
17b00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
17b10 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
17b20 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17b30 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
17b40 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
17b50 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
17b60 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
17b70 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
17b80 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
17b90 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
17ba0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
17bb0 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
17bc0 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
17bd0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
17be0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
17bf0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
17c00 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
17c10 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
17c20 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
17c30 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
17c40 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
17c50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17c60 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
17c70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
17c80 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
17c90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
17ca0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
17cb0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
17cc0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
17cd0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
17ce0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
17cf0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
17d00 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
17d10 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
17d20 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
17d30 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
17d40 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
17d50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
17d60 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
17d70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17d80 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
17d90 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
17da0 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
17db0 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
17dc0 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
17dd0 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
17de0 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
17df0 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
17e00 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
17e10 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
17e20 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
17e30 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
17e40 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
17e50 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
17e60 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
17e70 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
17e80 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
17e90 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
17ea0 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
17eb0 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
17ec0 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
17ed0 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
17ee0 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
17ef0 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
17f00 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
17f10 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
17f20 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
17f30 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
17f40 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
17f50 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
17f60 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
17f70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
17f80 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
17f90 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
17fa0 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
17fb0 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
17fc0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
17fd0 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
17fe0 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
17ff0 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
18000 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
18010 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
18020 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
18030 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
18040 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
18050 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
18060 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
18070 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
18080 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
18090 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
180a0 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
180b0 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
180c0 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
180d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
180e0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
180f0 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
18100 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
18110 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
18120 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
18130 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
18140 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
18150 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
18160 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
18170 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
18180 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
18190 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
181a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
181b0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
181c0 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
181d0 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
181e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
181f0 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  RI]] <dt>SQLITE_
18200 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64  CONFIG_URI.** <d
18210 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  d> This option t
18220 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
18230 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
18240 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  nt. If non-zero,
18250 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e   then.** URI han
18260 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
18270 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
18280 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
18290 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
182a0 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f  ndling.** is glo
182b0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20  bally disabled. 
182c0 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
182d0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
182e0 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d  led, all filenam
182f0 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20  es.** passed to 
18300 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
18310 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
18320 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
18330 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  open16()] or.** 
18340 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
18350 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f  t of [ATTACH] co
18360 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72  mmands are inter
18370 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20  preted as URIs, 
18380 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
18390 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
183a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
183b0 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65  _URI] flag is se
183c0 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  t when the datab
183d0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
183e0 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20  n is opened. If 
183f0 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
18400 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
18410 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
18420 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
18430 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
18440 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
18450 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
18460 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
18470 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
18480 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49   By default, URI
18490 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
184a0 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
184b0 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
184c0 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
184d0 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
184e0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
184f0 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
18500 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  mbol defined..**
18510 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
18520 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
18530 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
18540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
18550 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
18560 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74  ** <dd> This opt
18570 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
18580 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d  le integer argum
18590 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
185a0 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61  erpreted as.** a
185b0 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65   boolean in orde
185c0 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  r to enable or d
185d0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
185e0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
185f0 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74  es for.** full t
18600 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68  able scans in th
18610 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
18620 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
18630 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
18640 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
18650 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
18660 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
18670 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
18680 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
18690 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
186a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
186b0 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
186c0 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
186d0 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
186e0 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
186f0 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
18700 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
18710 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
18720 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
18730 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
18740 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
18750 69 6f 6e 0a 2a 2a 20 6d 61 6c 66 75 6e 63 74 69  ion.** malfuncti
18760 6f 6e 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  on when the opti
18770 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
18780 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
18790 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
187a0 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
187b0 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
187c0 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
187d0 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
187e0 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
187f0 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
18800 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
18810 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
18820 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
18830 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
18840 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
18850 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
18860 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
18870 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
18880 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
18890 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
188a0 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
188b0 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
188c0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
188d0 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
188e0 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
188f0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
18900 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
18910 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
18920 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
18930 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
18940 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
18950 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
18960 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
18970 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
18980 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
18990 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
189a0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
189b0 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
189c0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
189d0 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
189e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
189f0 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
18a00 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
18a10 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
18a20 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
18a30 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
18a40 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
18a50 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
18a60 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
18a70 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
18a80 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
18a90 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
18aa0 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
18ab0 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
18ac0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
18ad0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
18ae0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
18af0 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
18b00 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
18b10 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
18b20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18b30 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
18b40 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18b50 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
18b60 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
18b70 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
18b80 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
18b90 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
18ba0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
18bb0 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
18bc0 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
18bd0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
18be0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
18bf0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
18c00 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
18c10 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
18c20 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
18c30 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
18c40 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
18c50 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
18c60 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
18c70 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
18c80 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
18c90 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
18ca0 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
18cb0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
18cc0 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
18cd0 68 69 73 20 63 61 73 65 2e 0a 2a 2a 20 3c 2f 64  his case..** </d
18ce0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
18cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
18d00 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
18d10 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
18d20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
18d30 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
18d40 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
18d50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
18d60 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
18d70 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
18d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
18d90 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
18da0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
18db0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
18dc0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18dd0 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
18de0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
18df0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
18e00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18e10 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
18e20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
18e30 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
18e40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18e50 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
18e60 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
18e70 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
18e80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18e90 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
18ea0 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
18eb0 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
18ec0 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
18ed0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
18ee0 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
18ef0 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
18f00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18f10 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
18f20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
18f30 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
18f40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18f50 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
18f60 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
18f70 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
18f80 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
18f90 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
18fa0 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
18fb0 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
18fc0 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
18fd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
18fe0 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
18ff0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
19000 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19010 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
19020 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  14  /* no-op */.
19030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19040 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
19050 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20     15  /* no-op 
19060 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19070 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
19080 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
19090 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  nc, void* */.#de
190a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
190b0 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  IG_URI          
190c0 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  17  /* int */.#d
190d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
190e0 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20  FIG_PCACHE2     
190f0 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   18  /* sqlite3_
19100 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
19110 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19120 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
19130 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71  CHE2   19  /* sq
19140 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
19150 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
19160 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19170 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
19180 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a  CAN 20  /* int *
19190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
191a0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20  _CONFIG_SQLLOG  
191b0 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c       21  /* xSql
191c0 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f  log, void* */../
191d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
191e0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
191f0 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
19200 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
19210 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
19220 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
19230 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
19240 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
19250 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
19260 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
19270 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
19280 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
19290 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
192a0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
192b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
192c0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
192d0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
192e0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
192f0 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
19300 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
19310 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
19320 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
19330 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
19340 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
19350 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
19360 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
19370 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
19380 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
19390 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
193a0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
193b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
193c0 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
193d0 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
193e0 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
193f0 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
19400 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
19410 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
19420 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
19430 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
19440 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
19450 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
19460 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
19470 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
19480 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
19490 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
194a0 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
194b0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
194c0 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
194d0 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
194e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
194f0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
19500 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
19510 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
19520 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
19530 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
19540 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
19550 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
19560 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
19570 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
19580 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
19590 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
195a0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
195b0 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
195c0 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
195d0 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
195e0 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
195f0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
19600 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
19610 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
19620 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
19630 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
19640 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
19650 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
19660 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
19670 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
19680 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
19690 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
196a0 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
196b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
196c0 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
196d0 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
196e0 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
196f0 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
19700 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
19710 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
19720 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
19730 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
19740 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
19750 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
19760 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
19770 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
19780 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
19790 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
197a0 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
197b0 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
197c0 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
197d0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
197e0 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
197f0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
19800 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
19810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19820 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
19830 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
19840 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
19850 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
19860 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
19870 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
19880 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
19890 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
198a0 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
198b0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
198c0 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
198d0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
198e0 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
198f0 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
19900 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
19910 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
19920 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
19930 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
19940 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
19950 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
19960 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
19970 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
19980 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
19990 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
199a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
199b0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
199c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
199d0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
199e0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
199f0 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
19a00 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
19a10 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
19a20 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
19a30 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
19a40 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
19a50 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
19a60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
19a70 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
19a80 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
19a90 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
19aa0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
19ab0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
19ac0 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
19ad0 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
19ae0 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
19af0 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
19b00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19b10 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19b20 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19b30 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19b40 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19b50 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
19b60 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
19b70 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
19b80 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
19b90 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19ba0 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
19bb0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
19bc0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
19bd0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
19be0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
19bf0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
19c00 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
19c10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19c20 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
19c30 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
19c40 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
19c50 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
19c60 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
19c70 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
19c80 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
19c90 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
19ca0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
19cb0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
19cc0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
19cd0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
19ce0 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
19cf0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
19d00 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
19d10 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
19d20 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
19d30 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
19d40 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19d50 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
19d60 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
19d70 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
19d80 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
19d90 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
19da0 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
19db0 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
19dc0 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
19dd0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
19de0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19df0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
19e00 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
19e10 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
19e20 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
19e30 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
19e40 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
19e50 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
19e60 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19e70 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
19e80 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
19e90 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
19ea0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
19eb0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
19ec0 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20     1002  /* int 
19ed0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
19ee0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19ef0 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
19f00 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1003  /* int int
19f10 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  * */.../*.** CAP
19f20 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
19f30 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
19f40 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
19f50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19f60 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
19f70 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
19f80 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
19f90 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
19fa0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
19fb0 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
19fc0 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
19fd0 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
19fe0 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
19ff0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
1a000 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
1a010 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53  patibility..*/.S
1a020 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1a030 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
1a040 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
1a050 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
1a060 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a070 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
1a080 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  owid.**.** ^Each
1a090 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
1a0a0 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
1a0b0 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
1a0c0 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
1a0d0 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
1a0e0 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
1a0f0 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
1a100 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
1a110 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
1a120 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
1a130 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
1a140 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
1a150 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
1a160 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
1a170 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
1a180 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
1a190 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
1a1a0 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
1a1b0 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
1a1c0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
1a1d0 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
1a1e0 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
1a1f0 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
1a200 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  wid..**.** ^This
1a210 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1a220 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
1a230 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
1a240 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
1a250 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
1a260 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
1a270 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1a280 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
1a290 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1a2a0 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65  .  ^As of SQLite
1a2b0 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
1a2c0 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  this routines.**
1a2d0 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73   records the las
1a2e0 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f  t insert rowid o
1a2f0 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20  f both ordinary 
1a300 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74  tables and [virt
1a310 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20  ual tables]..** 
1a320 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
1a330 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
1a340 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
1a350 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
1a360 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
1a370 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
1a380 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
1a390 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
1a3a0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1a3b0 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
1a3c0 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
1a3d0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
1a3e0 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
1a3f0 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
1a400 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
1a410 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
1a420 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
1a430 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
1a440 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
1a450 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
1a460 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
1a470 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
1a480 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
1a490 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
1a4a0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
1a4b0 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
1a4c0 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
1a4d0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
1a4e0 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
1a4f0 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
1a500 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
1a510 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
1a520 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
1a530 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
1a540 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
1a550 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
1a560 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
1a570 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a580 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
1a590 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
1a5a0 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
1a5b0 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
1a5c0 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
1a5d0 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
1a5e0 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
1a5f0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
1a600 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1a610 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
1a620 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
1a630 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
1a640 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
1a650 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
1a660 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
1a670 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
1a680 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
1a690 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
1a6a0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
1a6b0 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
1a6c0 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
1a6d0 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
1a6e0 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
1a6f0 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
1a700 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
1a710 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
1a720 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
1a730 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
1a740 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
1a750 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
1a760 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
1a770 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
1a780 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
1a790 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
1a7a0 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
1a7b0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
1a7c0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
1a7d0 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
1a7e0 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
1a7f0 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
1a800 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a810 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1a820 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1a830 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
1a840 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
1a850 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
1a860 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1a870 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
1a880 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
1a890 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
1a8a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
1a8b0 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
1a8c0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
1a8d0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
1a8e0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
1a8f0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
1a900 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1a910 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
1a920 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
1a930 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
1a940 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
1a950 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
1a960 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
1a970 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  owid]..*/.SQLITE
1a980 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
1a990 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
1a9a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
1a9b0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1a9c0 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
1a9d0 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
1a9e0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
1a9f0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1aa00 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1aa10 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
1aa20 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68  ows that were ch
1aa30 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65  anged.** or inse
1aa40 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20  rted or deleted 
1aa50 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
1aa60 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53  ntly completed S
1aa70 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1aa80 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
1aa90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
1aaa0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
1aab0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
1aac0 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73  * ^(Only changes
1aad0 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
1aae0 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
1aaf0 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  the [INSERT], [U
1ab00 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44  PDATE],.** or [D
1ab10 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
1ab20 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41   are counted.  A
1ab30 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
1ab40 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72   caused by.** tr
1ab50 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69  iggers or [forei
1ab60 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
1ab70 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1ab80 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73  )^ Use the.** [s
1ab90 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1aba0 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
1abb0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74   to find the tot
1abc0 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  al number of cha
1abd0 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e  nges.** includin
1abe0 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
1abf0 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64   by triggers and
1ac00 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74   foreign key act
1ac10 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61  ions..**.** ^Cha
1ac20 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
1ac30 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65  hat are simulate
1ac40 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44  d by an [INSTEAD
1ac50 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20   OF trigger].** 
1ac60 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1ac70 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c    Only real tabl
1ac80 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
1ac90 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  unted..**.** ^(A
1aca0 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
1acb0 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
1acc0 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
1acd0 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
1ace0 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
1acf0 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
1ad00 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
1ad10 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
1ad20 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
1ad30 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52  de effects of [R
1ad40 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
1ad50 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a  nt resolution,.*
1ad60 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52  * rollback, ABOR
1ad70 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44  T processing, [D
1ad80 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62  ROP TABLE], or b
1ad90 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d  y any other.** m
1ada0 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74  echanisms do not
1adb0 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74   count as direct
1adc0 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a   row changes.)^.
1add0 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
1ade0 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
1adf0 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
1ae00 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
1ae10 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
1ae20 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b  he script of a [
1ae30 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
1ae40 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d   trigger]. .** M
1ae50 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
1ae60 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
1ae70 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
1ae80 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
1ae90 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
1aea0 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
1aeb0 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
1aec0 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
1aed0 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
1aee0 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
1aef0 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
1af00 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
1af10 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
1af20 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
1af30 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
1af40 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
1af50 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
1af60 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1af70 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1af80 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
1af90 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
1afa0 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
1afb0 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
1afc0 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
1afd0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1afe0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1aff0 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f  ber of direct ro
1b000 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  w changes in the
1b010 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
1b020 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
1b030 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1b040 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
1b050 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  ame.** trigger c
1b060 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
1b070 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64  hus, when called
1b080 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
1b090 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69  vel, this functi
1b0a0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
1b0b0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  * number of chan
1b0c0 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
1b0d0 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
1b0e0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
1b0f0 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63  .** that also oc
1b100 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f  curred at the to
1b110 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68  p level.  ^(With
1b120 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
1b130 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
1b140 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1b150 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
1b160 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
1b170 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
1b180 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
1b190 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
1b1a0 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
1b1b0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1b1c0 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
1b1d0 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
1b1e0 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
1b1f0 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
1b200 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
1b210 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
1b220 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
1b230 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
1b240 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
1b250 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
1b260 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a  own context.)^.*
1b270 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
1b280 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1b290 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1b2a0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
1b2b0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1b2c0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
1b2d0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1b2e0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1b2f0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1b300 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1b310 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1b320 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b330 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1b340 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
1b350 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1b360 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1b370 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
1b380 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1b390 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  ningful..*/.SQLI
1b3a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1b3b0 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
1b3c0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1b3d0 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
1b3e0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
1b3f0 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
1b400 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1b410 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1b420 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
1b430 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a  ed by [INSERT],.
1b440 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ** [UPDATE] or [
1b450 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
1b460 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
1b470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b480 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
1b490 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65  * ^(The count re
1b4a0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1b4b0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1b4c0 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  ) includes all c
1b4d0 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61  hanges.** from a
1b4e0 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  ll [CREATE TRIGG
1b4f0 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f  ER | trigger] co
1b500 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67  ntexts and chang
1b510 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66  es made by.** [f
1b520 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
1b530 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ns]. However,.**
1b540 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
1b550 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
1b560 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
1b570 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
1b580 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
1b590 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
1b5a0 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
1b5b0 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
1b5c0 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
1b5d0 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
1b5e0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
1b5f0 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
1b600 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
1b610 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
1b620 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
1b630 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1b640 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
1b650 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
1b660 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
1b670 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20  e counted.)^.** 
1b680 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74  ^The sqlite3_tot
1b690 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  al_changes() fun
1b6a0 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65  ction counts the
1b6b0 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e   changes as soon
1b6c0 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   as.** the state
1b6d0 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
1b6e0 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
1b6f0 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
1b700 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20  ement handle.** 
1b710 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
1b720 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
1b730 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
1b740 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
1b750 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1b760 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1b770 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1b780 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1b790 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1b7a0 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
1b7b0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1b7c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1b7d0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1b7e0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1b7f0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1b800 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1b810 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
1b820 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
1b830 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1b840 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
1b850 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
1b860 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1b870 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  ningful..*/.SQLI
1b880 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1b890 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1b8a0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1b8b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
1b8c0 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
1b8d0 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
1b8e0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1b8f0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
1b900 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
1b910 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
1b920 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
1b930 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
1b940 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
1b950 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
1b960 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
1b970 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
1b980 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
1b990 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
1b9a0 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
1b9b0 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
1b9c0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
1b9d0 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
1b9e0 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
1b9f0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
1ba00 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
1ba10 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
1ba20 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
1ba30 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
1ba40 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
1ba50 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1ba60 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
1ba70 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
1ba80 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
1ba90 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1baa0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
1bab0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1bac0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
1bad0 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
1bae0 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
1baf0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1bb00 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1bb10 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
1bb20 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
1bb30 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
1bb40 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
1bb50 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1bb60 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
1bb70 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
1bb80 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
1bb90 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
1bba0 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
1bbb0 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
1bbc0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
1bbd0 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
1bbe0 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
1bbf0 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
1bc00 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
1bc10 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
1bc20 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
1bc30 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1bc40 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1bc50 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1bc60 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
1bc70 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
1bc80 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
1bc90 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
1bca0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
1bcb0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
1bcc0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
1bcd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
1bce0 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
1bcf0 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
1bd00 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
1bd10 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1bd20 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
1bd30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bd40 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
1bd50 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
1bd60 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1bd70 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1bd80 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1bd90 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
1bda0 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
1bdb0 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
1bdc0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
1bdd0 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
1bde0 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
1bdf0 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
1be00 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
1be10 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1be20 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
1be30 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1be40 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1be50 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
1be60 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
1be70 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
1be80 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
1be90 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1bea0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
1beb0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
1bec0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1bed0 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
1bee0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
1bef0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1bf00 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
1bf10 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
1bf20 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
1bf30 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1bf40 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1bf50 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1bf60 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1bf70 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1bf80 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1bf90 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
1bfa0 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
1bfb0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
1bfc0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1bfd0 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
1bfe0 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
1bff0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1c000 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
1c010 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
1c020 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c030 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1c040 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
1c050 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
1c060 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1c070 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
1c080 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
1c090 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
1c0a0 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
1c0b0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
1c0c0 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
1c0d0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1c0e0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
1c0f0 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
1c100 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
1c110 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
1c120 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
1c130 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
1c140 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
1c150 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
1c160 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
1c170 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
1c180 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1c190 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
1c1a0 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
1c1b0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
1c1c0 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
1c1d0 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
1c1e0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
1c1f0 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
1c200 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
1c210 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
1c220 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
1c230 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
1c240 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
1c250 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
1c260 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
1c270 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
1c280 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
1c290 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
1c2a0 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
1c2b0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
1c2c0 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
1c2d0 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
1c2e0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
1c2f0 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
1c300 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
1c310 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
1c320 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
1c330 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
1c340 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
1c350 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
1c360 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1c370 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
1c380 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1c390 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
1c3a0 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
1c3b0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
1c3c0 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
1c3d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1c3e0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1c3f0 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
1c400 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1c410 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
1c420 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
1c430 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
1c440 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
1c450 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
1c460 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
1c470 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
1c480 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
1c490 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
1c4a0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
1c4b0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
1c4c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
1c4d0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
1c4e0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1c4f0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
1c500 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
1c510 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
1c520 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
1c530 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
1c540 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
1c550 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
1c560 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
1c570 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1c580 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1c590 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
1c5a0 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
1c5b0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1c5c0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1c5d0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1c5e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1c5f0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
1c600 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1c610 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1c620 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1c630 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1c640 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1c650 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1c660 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49  e order..*/.SQLI
1c670 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1c680 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
1c690 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51  t char *sql);.SQ
1c6a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1c6b0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1c6c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
1c6d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c6e0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
1c6f0 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
1c700 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
1c710 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
1c720 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
1c730 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1c740 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
1c750 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
1c760 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
1c770 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
1c780 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
1c790 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
1c7a0 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
1c7b0 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
1c7c0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
1c7d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1c7e0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
1c7f0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
1c800 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
1c810 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
1c820 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
1c830 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
1c840 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
1c850 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
1c860 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1c870 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
1c880 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1c890 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
1c8a0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
1c8b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1c8c0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1c8d0 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
1c8e0 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
1c8f0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
1c900 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1c910 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
1c920 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
1c930 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1c940 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
1c950 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1c960 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1c970 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
1c980 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
1c990 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
1c9a0 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
1c9b0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
1c9c0 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
1c9d0 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
1c9e0 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
1c9f0 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
1ca00 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
1ca10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1ca20 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
1ca30 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
1ca40 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
1ca50 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
1ca60 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1ca70 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1ca80 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
1ca90 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
1caa0 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
1cab0 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
1cac0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
1cad0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
1cae0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
1caf0 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
1cb00 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
1cb10 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
1cb20 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
1cb30 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
1cb40 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
1cb50 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
1cb60 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
1cb70 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
1cb80 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
1cb90 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
1cba0 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
1cbb0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
1cbc0 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
1cbd0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
1cbe0 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
1cbf0 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
1cc00 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
1cc10 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
1cc20 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
1cc30 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1cc40 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
1cc50 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
1cc60 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
1cc70 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
1cc80 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
1cc90 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1cca0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
1ccb0 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
1ccc0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
1ccd0 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
1cce0 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
1ccf0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
1cd00 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
1cd10 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1cd20 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
1cd30 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1cd40 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
1cd50 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
1cd60 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1cd70 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
1cd80 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
1cd90 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
1cda0 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
1cdb0 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
1cdc0 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
1cdd0 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
1cde0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1cdf0 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
1ce00 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
1ce10 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
1ce20 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
1ce30 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
1ce40 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
1ce50 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
1ce60 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
1ce70 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
1ce80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
1ce90 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
1cea0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
1ceb0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
1cec0 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
1ced0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
1cee0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
1cef0 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
1cf00 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
1cf10 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
1cf20 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
1cf30 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
1cf40 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
1cf50 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
1cf60 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
1cf70 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
1cf80 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
1cf90 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
1cfa0 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
1cfb0 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
1cfc0 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
1cfd0 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
1cfe0 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
1cff0 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
1d000 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
1d010 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
1d020 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
1d030 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
1d040 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
1d050 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
1d060 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
1d070 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
1d080 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
1d090 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
1d0a0 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
1d0b0 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
1d0c0 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
1d0d0 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
1d0e0 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
1d0f0 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
1d100 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
1d110 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
1d120 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
1d130 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
1d140 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
1d150 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
1d160 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
1d170 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
1d180 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
1d190 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
1d1a0 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
1d1b0 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
1d1c0 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
1d1d0 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
1d1e0 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
1d1f0 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
1d200 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
1d210 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
1d220 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1d230 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1d240 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
1d250 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
1d260 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
1d270 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
1d280 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
1d290 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
1d2a0 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
1d2b0 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
1d2c0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
1d2d0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
1d2e0 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
1d2f0 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
1d300 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
1d310 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
1d320 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
1d330 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
1d340 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
1d350 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1d360 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1d370 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1d380 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
1d390 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1d3a0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1d3b0 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1d3c0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1d3d0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1d3e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d3f0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1d400 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1d410 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1d420 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1d430 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1d440 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
1d450 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1d460 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
1d470 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
1d480 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1d490 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
1d4a0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1d4b0 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
1d4c0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1d4d0 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
1d4e0 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
1d4f0 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
1d500 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
1d510 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
1d520 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
1d530 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
1d540 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
1d550 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
1d560 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1d570 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
1d580 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
1d590 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
1d5a0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1d5b0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1d5c0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
1d5d0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
1d5e0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
1d5f0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
1d600 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
1d610 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
1d620 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
1d630 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1d640 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
1d650 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
1d660 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
1d670 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
1d680 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
1d690 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
1d6a0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1d6b0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1d6c0 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
1d6d0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1d6e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d6f0 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
1d700 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1d710 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1d720 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1d730 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1d740 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1d750 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1d760 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1d770 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1d780 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1d790 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51  cleared.)^.*/.SQ
1d7a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1d7b0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1d7c0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1d7d0 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
1d7e0 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
1d7f0 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
1d800 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
1d810 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1d820 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1d830 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1d840 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1d850 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1d860 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1d870 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1d880 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1d890 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1d8a0 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1d8b0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1d8c0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1d8d0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1d8e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d8f0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1d900 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1d910 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1d920 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1d930 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1d940 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1d950 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1d960 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1d970 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1d980 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1d990 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1d9a0 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1d9b0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1d9c0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1d9d0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1d9e0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1d9f0 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1da00 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1da10 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1da20 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1da30 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1da40 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1da50 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1da60 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1da70 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1da80 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1da90 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1daa0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1dab0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1dac0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1dad0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1dae0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1daf0 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1db00 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1db10 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1db20 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1db30 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1db40 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1db50 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1db60 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1db70 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1db80 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1db90 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1dba0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1dbb0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1dbc0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1dbd0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1dbe0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1dbf0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1dc00 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1dc10 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1dc20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1dc30 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1dc40 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1dc50 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1dc60 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1dc70 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1dc80 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1dc90 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1dca0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1dcb0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1dcc0 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1dcd0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1dce0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1dcf0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1dd00 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1dd10 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1dd20 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1dd30 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1dd40 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1dd50 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1dd60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1dd70 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1dd80 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1dd90 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1dda0 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1ddb0 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1ddc0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ddd0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1dde0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1ddf0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1de00 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1de10 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1de20 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1de30 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1de40 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1de50 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1de60 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1de70 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1de80 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1de90 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1dea0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1deb0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1dec0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1ded0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1dee0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1def0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1df00 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1df10 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1df20 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1df30 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1df40 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1df50 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1df60 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1df70 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1df80 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1df90 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1dfa0 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1dfb0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1dfc0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1dfd0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1dfe0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1dff0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1e000 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1e010 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1e020 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1e030 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1e040 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1e050 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1e060 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1e070 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1e080 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1e090 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1e0a0 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1e0b0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1e0c0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1e0d0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1e0e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1e0f0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1e100 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1e110 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1e120 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1e130 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1e140 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1e150 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1e160 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1e170 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1e180 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1e190 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1e1a0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1e1b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1e1c0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1e1d0 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1e1e0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1e1f0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1e200 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1e210 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1e220 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1e230 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1e240 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1e250 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1e260 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1e270 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1e280 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1e290 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1e2a0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1e2b0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1e2c0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1e2d0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1e2e0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1e2f0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1e300 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1e310 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1e320 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1e330 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1e340 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1e350 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1e360 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1e370 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1e380 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1e390 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1e3a0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1e3b0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1e3c0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1e3d0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1e3e0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1e3f0 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1e400 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1e410 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1e420 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1e430 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1e440 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1e450 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  PI int sqlite3_g
1e460 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
1e470 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1e480 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
1e490 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
1e4a0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1e4b0 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
1e4c0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
1e4d0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
1e4e0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
1e4f0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
1e500 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
1e510 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1e520 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
1e530 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1e540 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
1e550 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1e560 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
1e570 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
1e580 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1e590 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
1e5a0 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
1e5b0 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  here */.);.SQLIT
1e5c0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1e5d0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1e5e0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1e5f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1e600 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1e610 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1e620 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1e630 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1e640 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1e650 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1e660 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1e670 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1e680 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1e690 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e6a0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1e6b0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1e6c0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1e6d0 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1e6e0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1e6f0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1e700 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1e710 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1e720 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1e730 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1e740 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1e750 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1e760 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1e770 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1e780 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1e790 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1e7a0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1e7b0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1e7c0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1e7d0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1e7e0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1e7f0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1e800 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1e810 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1e820 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1e830 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1e840 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1e850 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1e860 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1e870 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1e880 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1e890 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1e8a0 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1e8b0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1e8c0 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1e8d0 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1e8e0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1e8f0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1e900 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1e910 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1e920 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1e930 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1e940 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1e950 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1e960 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1e970 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1e980 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1e990 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1e9a0 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1e9b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1e9c0 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1e9d0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1e9e0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1e9f0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1ea00 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1ea10 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1ea20 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1ea30 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1ea40 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1ea50 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1ea60 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1ea70 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1ea80 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1ea90 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1eaa0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1eab0 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1eac0 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1ead0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1eae0 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1eaf0 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1eb00 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1eb10 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1eb20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1eb30 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1eb40 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1eb50 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1eb60 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1eb70 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1eb80 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1eb90 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1eba0 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1ebb0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1ebc0 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1ebd0 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1ebe0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1ebf0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1ec00 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1ec10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ec20 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1ec30 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1ec40 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1ec50 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1ec60 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1ec70 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1ec80 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1ec90 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1eca0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1ecb0 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1ecc0 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1ecd0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1ece0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1ecf0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1ed00 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1ed10 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1ed20 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1ed30 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
1ed40 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
1ed50 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
1ed60 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1ed70 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
1ed80 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
1ed90 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
1eda0 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
1edb0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
1edc0 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
1edd0 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
1ede0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
1edf0 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
1ee00 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
1ee10 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
1ee20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
1ee30 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
1ee40 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
1ee50 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
1ee60 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
1ee70 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
1ee80 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
1ee90 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1eea0 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
1eeb0 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
1eec0 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
1eed0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1eee0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1eef0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
1ef00 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
1ef10 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
1ef20 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1ef30 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
1ef40 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
1ef50 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1ef60 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1ef70 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1ef80 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1ef90 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1efa0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1efb0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1efc0 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1efd0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1efe0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1eff0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1f000 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1f010 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1f020 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1f030 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1f040 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1f050 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1f060 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1f070 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1f080 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1f090 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1f0a0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1f0b0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1f0c0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1f0d0 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1f0e0 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1f0f0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1f100 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1f110 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1f120 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1f130 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1f140 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1f150 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1f160 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1f170 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1f180 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1f190 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1f1a0 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1f1b0 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1f1c0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1f1d0 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1f1e0 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1f1f0 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1f200 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1f210 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1f220 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1f230 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1f240 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1f250 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1f260 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1f270 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1f280 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1f290 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1f2a0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1f2b0 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1f2c0 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1f2d0 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1f2e0 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1f2f0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1f300 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1f310 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1f320 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1f330 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1f340 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1f350 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1f360 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1f370 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1f380 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1f390 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1f3a0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1f3b0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1f3c0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1f3d0 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1f3e0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1f3f0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1f400 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1f410 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1f420 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1f430 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1f440 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1f450 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1f460 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1f470 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1f480 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1f490 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1f4a0 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1f4b0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1f4c0 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1f4d0 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1f4e0 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1f4f0 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1f500 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1f510 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1f520 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1f530 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1f540 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1f550 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1f560 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1f570 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  ing.)^.*/.SQLITE
1f580 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1f590 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1f5a0 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c   char*,...);.SQL
1f5b0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1f5c0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
1f5d0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1f5e0 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ist);.SQLITE_API
1f5f0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1f600 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1f610 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1f620 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1f630 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1f640 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1f650 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1f660 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1f670 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1f680 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1f690 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1f6a0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1f6b0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1f6c0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1f6d0 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1f6e0 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1f6f0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1f700 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1f710 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1f720 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1f730 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1f740 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1f750 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1f760 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1f770 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1f780 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1f790 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1f7a0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1f7b0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1f7c0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1f7d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1f7e0 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1f7f0 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1f800 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1f810 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1f820 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1f830 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1f840 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1f850 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1f860 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1f870 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1f880 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1f890 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1f8a0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1f8b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1f8c0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1f8d0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1f8e0 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1f8f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1f900 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1f910 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1f920 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1f930 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1f940 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1f950 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1f960 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1f970 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1f980 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1f990 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1f9a0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1f9b0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1f9c0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1f9d0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1f9e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1f9f0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1fa00 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1fa10 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1fa20 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1fa30 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1fa40 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1fa50 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1fa60 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1fa70 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1fa80 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1fa90 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1faa0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1fab0 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1fac0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1fad0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1fae0 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1faf0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1fb00 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1fb10 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1fb20 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1fb30 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1fb40 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1fb50 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1fb60 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1fb70 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1fb80 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1fb90 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1fba0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
1fbb0 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
1fbc0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1fbd0 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1fbe0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1fbf0 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
1fc00 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
1fc10 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
1fc20 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
1fc30 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
1fc40 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
1fc50 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
1fc60 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
1fc70 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
1fc80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1fc90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1fca0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1fcb0 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1fcc0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1fcd0 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1fce0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1fcf0 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
1fd00 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1fd10 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1fd20 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
1fd30 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1fd40 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1fd50 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
1fd60 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1fd70 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1fd80 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1fd90 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1fda0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1fdb0 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
1fdc0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1fdd0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1fde0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
1fdf0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1fe00 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1fe10 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
1fe20 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
1fe30 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1fe40 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
1fe50 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
1fe60 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
1fe70 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
1fe80 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
1fe90 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1fea0 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
1feb0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
1fec0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1fed0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1fee0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1fef0 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
1ff00 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1ff10 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
1ff20 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1ff30 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1ff40 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1ff50 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
1ff60 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
1ff70 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
1ff80 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1ff90 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1ffa0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1ffb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
1ffc0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1ffd0 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
1ffe0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1fff0 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
20000 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
20010 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
20020 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
20030 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
20040 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
20050 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
20060 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
20070 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
20080 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
20090 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
200a0 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
200b0 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
200c0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
200d0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
200e0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
200f0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
20100 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
20110 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
20120 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
20130 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
20140 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
20150 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
20160 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
20170 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
20180 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
20190 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
201a0 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
201b0 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
201c0 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
201d0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
201e0 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
201f0 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
20200 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
20210 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
20220 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
20230 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
20240 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
20250 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
20260 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
20270 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
20280 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
20290 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
202a0 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
202b0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
202c0 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
202d0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
202e0 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
202f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
20300 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
20310 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
20320 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
20330 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
20340 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
20350 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
20360 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
20370 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
20380 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
20390 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
203a0 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
203b0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
203c0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
203d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
203e0 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
203f0 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
20400 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
20410 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
20420 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
20430 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
20440 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
20450 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
20460 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
20470 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
20480 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
20490 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
204a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
204b0 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
204c0 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  (int);.SQLITE_AP
204d0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
204e0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
204f0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
20500 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
20510 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
20520 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
20530 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
20540 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
20550 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
20560 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
20570 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
20580 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
20590 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
205a0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
205b0 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
205c0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
205d0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
205e0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
205f0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
20600 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
20610 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
20620 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
20630 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
20640 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
20650 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
20660 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
20670 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
20680 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
20690 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
206a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
206b0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
206c0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
206d0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
206e0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
206f0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
20700 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
20710 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
20720 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
20730 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
20740 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
20750 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
20760 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
20770 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20780 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
20790 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
207a0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
207b0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
207c0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
207d0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
207e0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
207f0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
20800 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
20810 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
20820 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
20830 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
20840 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
20850 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
20860 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
20870 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
20880 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
20890 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
208a0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
208b0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
208c0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
208d0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
208e0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
208f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
20900 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
20910 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
20920 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
20930 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
20940 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
20950 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
20960 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
20970 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20980 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ed(void);.SQLITE
20990 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
209a0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
209b0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
209c0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
209d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
209e0 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
209f0 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
20a00 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
20a10 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
20a20 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
20a30 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
20a40 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
20a50 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
20a60 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
20a70 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
20a80 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
20a90 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
20aa0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
20ab0 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
20ac0 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
20ad0 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
20ae0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
20af0 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
20b00 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
20b10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
20b20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
20b30 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
20b40 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
20b50 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
20b60 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
20b70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
20b80 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
20b90 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
20ba0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
20bb0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
20bc0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
20bd0 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
20be0 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
20bf0 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
20c00 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
20c10 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
20c20 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
20c30 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
20c40 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
20c50 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
20c60 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
20c70 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
20c80 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20   object..** ^On 
20c90 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
20ca0 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
20cb0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
20cc0 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
20cd0 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
20ce0 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
20cf0 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
20d00 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
20d10 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
20d20 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
20d30 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
20d40 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
20d50 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
20d60 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
20d70 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
20d80 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
20d90 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
20da0 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
20db0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20dc0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
20dd0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
20de0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
20df0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
20e00 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
20e10 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
20e20 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
20e30 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
20e40 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
20e50 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
20e60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
20e70 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
20e80 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
20e90 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
20ea0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
20eb0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
20ec0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
20ed0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
20ee0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
20ef0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
20f00 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
20f10 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
20f20 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
20f30 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
20f40 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20f50 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
20f60 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
20f70 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
20f80 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
20f90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20fa0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
20fb0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
20fc0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
20fd0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
20fe0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
20ff0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
21000 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
21010 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
21020 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
21030 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
21040 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
21050 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
21060 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
21070 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
21080 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
21090 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
210a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
210b0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
210c0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
210d0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
210e0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
210f0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
21100 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
21110 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
21120 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
21130 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
21140 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
21150 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
21160 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
21170 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
21180 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
21190 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
211a0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
211b0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
211c0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
211d0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
211e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
211f0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
21200 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
21210 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21220 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
21230 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
21240 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
21250 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
21260 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
21270 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
21280 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
21290 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
212a0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
212b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
212c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
212d0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
212e0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
212f0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
21300 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21310 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
21320 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
21330 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
21340 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
21350 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
21360 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
21370 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
21380 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
21390 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
213a0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
213b0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
213c0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
213d0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
213e0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
213f0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
21400 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
21410 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
21420 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
21430 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
21440 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
21450 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
21460 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
21470 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
21480 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
21490 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
214a0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
214b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
214c0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
214d0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
214e0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
214f0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
21500 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
21510 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
21520 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
21530 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
21540 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
21550 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
21560 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
21570 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
21580 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
21590 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
215a0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
215b0 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
215c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
215d0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
215e0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
215f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
21600 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
21610 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
21620 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
21630 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
21640 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
21650 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
21660 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
21670 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
21680 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
21690 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
216a0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
216b0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
216c0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
216d0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
216e0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
216f0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
21700 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
21710 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
21720 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
21730 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
21740 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
21750 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
21760 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
21770 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
21780 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
21790 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
217a0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
217b0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
217c0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
217d0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
217e0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
217f0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
21800 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
21810 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
21820 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
21830 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
21840 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
21850 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
21860 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
21870 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
21880 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
21890 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
218a0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
218b0 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
218c0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
218d0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
218e0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
218f0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
21900 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
21910 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
21920 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
21930 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
21940 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
21950 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
21960 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
21970 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
21980 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
21990 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
219a0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
219b0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
219c0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
219d0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
219e0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
219f0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
21a00 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
21a10 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
21a20 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
21a30 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
21a40 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
21a50 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
21a60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
21a70 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
21a80 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
21a90 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
21aa0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
21ab0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
21ac0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
21ad0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
21ae0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
21af0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
21b00 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
21b10 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
21b20 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
21b30 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21b40 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
21b50 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
21b60 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
21b70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21b80 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
21b90 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21ba0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
21bb0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
21bc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
21bd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21be0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
21bf0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
21c00 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
21c10 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
21c20 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
21c30 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
21c40 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
21c50 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
21c60 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
21c70 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
21c80 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
21c90 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
21ca0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
21cb0 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
21cc0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
21cd0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
21ce0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
21cf0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
21d00 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
21d10 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
21d20 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
21d30 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
21d40 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
21d50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
21d60 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
21d70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21d80 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
21d90 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
21da0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
21db0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
21dc0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
21dd0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
21de0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
21df0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
21e00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
21e10 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
21e20 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
21e30 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
21e40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
21e50 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
21e60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
21e70 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
21e80 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
21e90 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
21ea0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
21eb0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21ec0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
21ed0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
21ee0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
21ef0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
21f00 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
21f10 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
21f20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
21f30 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
21f40 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
21f50 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
21f60 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
21f70 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
21f80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21f90 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
21fa0 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
21fb0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
21fc0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
21fd0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
21fe0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
21ff0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
22000 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
22010 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
22020 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
22030 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
22040 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
22050 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
22060 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
22070 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
22080 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
22090 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
220a0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
220b0 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42   a [SQLITE_ROLLB
220c0 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64  ACK | return cod
220d0 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b  e].** from the [
220e0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
220f0 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65  conflict()] inte
22100 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
22110 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
22120 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
22130 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
22140 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
22150 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
22160 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
22170 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
22180 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
22190 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
221a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
221b0 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
221c0 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
221d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
221e0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
221f0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
22200 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
22210 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
22220 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
22230 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
22240 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
22250 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
22260 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
22270 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
22280 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
22290 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
222a0 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
222b0 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
222c0 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
222d0 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
222e0 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
222f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
22300 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
22310 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
22320 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
22330 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
22340 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
22350 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
22360 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
22370 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
22380 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
22390 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
223a0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
223b0 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
223c0 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
223d0 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
223e0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
223f0 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
22400 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
22410 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
22420 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
22430 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
22440 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
22450 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
22460 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
22470 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
22480 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
22490 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
224a0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
224b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
224c0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
224d0 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
224e0 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
224f0 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
22500 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
22510 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
22520 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
22530 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
22540 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
22550 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
22560 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
22570 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22580 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22590 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
225a0 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
225b0 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
225c0 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
225d0 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
225e0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
225f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22600 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22610 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
22620 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
22630 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22640 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22650 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22660 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
22670 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
22680 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
22690 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
226a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
226b0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
226c0 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
226d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
226e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
226f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22700 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
22710 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
22720 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
22730 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22750 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
22760 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
22770 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
22780 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22790 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
227a0 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
227b0 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
227c0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
227d0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
227e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
227f0 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
22800 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
22810 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
22820 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22830 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
22840 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
22850 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
22860 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22870 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22880 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22890 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
228a0 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
228b0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
228c0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
228d0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
228e0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
228f0 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
22900 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22910 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22920 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
22930 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
22940 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
22950 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
22960 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22970 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
22980 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
22990 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
229a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
229b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
229c0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
229d0 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
229e0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
229f0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
22a00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22a10 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
22a20 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
22a30 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
22a40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22a50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22a60 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
22a70 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
22a80 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
22a90 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22aa0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22ab0 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
22ac0 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
22ad0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
22ae0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22af0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22b00 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
22b10 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
22b20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22b30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22b40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22b50 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
22b60 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
22b70 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
22b80 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
22b90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22ba0 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
22bb0 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
22bc0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
22bd0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
22be0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22bf0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
22c00 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
22c10 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
22c20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22c30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
22c40 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
22c50 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
22c60 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
22c70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22c80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
22c90 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
22ca0 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
22cb0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
22cc0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
22cd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
22ce0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
22cf0 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
22d00 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
22d10 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22d20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
22d30 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
22d40 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
22d50 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
22d60 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22d70 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
22d80 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
22d90 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
22da0 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
22db0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22dc0 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
22dd0 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
22de0 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
22df0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22e00 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22e10 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
22e20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
22e30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22e40 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22e50 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22e60 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
22e70 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
22e80 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22e90 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
22ea0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22eb0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
22ec0 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
22ed0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22ee0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
22ef0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22f00 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
22f10 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
22f20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
22f30 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
22f40 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22f50 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
22f60 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
22f70 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
22f80 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
22f90 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22fa0 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
22fb0 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
22fc0 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
22fd0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
22fe0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
22ff0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
23000 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
23010 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
23020 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
23030 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
23040 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
23050 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
23060 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
23070 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
23080 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
23090 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
230a0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
230b0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
230c0 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
230d0 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
230e0 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
230f0 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
23100 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
23110 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
23120 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
23130 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
23140 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
23150 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
23160 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
23170 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
23180 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
23190 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
231a0 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
231b0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
231c0 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
231d0 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
231e0 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
231f0 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
23200 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
23210 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
23220 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
23230 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
23240 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
23250 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
23260 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
23270 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
23280 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
23290 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
232a0 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
232b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
232c0 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
232d0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
232e0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
232f0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
23300 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
23310 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
23320 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
23330 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
23340 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
23350 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
23360 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
23370 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
23380 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
23390 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
233a0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
233b0 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
233c0 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
233d0 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
233e0 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
233f0 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
23400 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
23410 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
23420 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
23430 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
23440 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
23450 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
23460 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
23470 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
23480 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
23490 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
234a0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
234b0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
234c0 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
234d0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
234e0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
234f0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
23500 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74   void *sqlite3_t
23510 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
23520 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
23530 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
23540 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
23550 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52  API SQLITE_EXPER
23560 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
23570 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
23580 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
23590 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
235a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
235b0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
235c0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
235d0 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
235e0 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
235f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
23600 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
23610 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
23620 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
23630 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
23640 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
23650 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
23660 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
23670 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
23680 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
23690 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
236a0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
236b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
236c0 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
236d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
236e0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
236f0 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
23700 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
23710 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
23720 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
23730 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
23740 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
23750 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
23760 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
23770 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
23780 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
23790 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
237a0 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62  er N is the numb
237b0 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
237c0 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
237d0 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
237e0 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
237f0 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
23800 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
23810 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
23820 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
23830 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
23840 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
23850 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
23860 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
23870 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
23880 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
23890 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
238a0 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
238b0 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
238c0 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
238d0 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
238e0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
238f0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
23900 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
23910 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
23920 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
23930 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
23940 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
23950 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
23960 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
23970 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
23980 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
23990 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
239a0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
239b0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
239c0 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
239d0 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
239e0 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
239f0 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
23a00 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
23a10 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
23a20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
23a30 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
23a40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
23a50 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
23a60 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
23a70 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
23a80 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
23a90 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
23aa0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
23ab0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
23ac0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
23ad0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
23ae0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
23af0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
23b00 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
23b10 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
23b20 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
23b30 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
23b40 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
23b50 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
23b60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23b70 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
23b80 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
23b90 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
23ba0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
23bb0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
23bc0 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
23bd0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
23be0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
23bf0 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
23c00 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
23c10 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
23c20 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
23c30 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
23c40 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
23c50 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
23c60 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
23c70 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
23c80 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
23c90 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
23ca0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
23cb0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
23cc0 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
23cd0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
23ce0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
23cf0 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
23d00 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
23d10 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
23d20 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
23d30 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
23d40 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
23d50 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
23d60 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
23d70 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
23d80 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
23d90 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
23da0 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
23db0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
23dc0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
23dd0 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
23de0 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
23df0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
23e00 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
23e10 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
23e20 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
23e30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
23e40 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
23e50 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
23e60 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
23e70 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
23e80 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
23e90 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
23ea0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
23eb0 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
23ec0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
23ed0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
23ee0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
23ef0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
23f00 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
23f10 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
23f20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
23f30 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
23f40 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
23f50 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
23f60 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
23f70 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
23f80 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
23f90 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
23fa0 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
23fb0 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
23fc0 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
23fd0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
23fe0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
23ff0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
24000 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
24010 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
24020 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
24030 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
24040 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
24050 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
24060 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
24070 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
24080 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
24090 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
240a0 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
240b0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
240c0 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
240d0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
240e0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
240f0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
24100 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
24110 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
24120 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
24130 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
24140 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
24150 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
24160 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
24170 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
24180 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
24190 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
241a0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
241b0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
241c0 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
241d0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
241e0 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
241f0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
24200 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
24210 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
24220 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
24230 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
24240 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
24250 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
24260 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
24270 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
24280 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
24290 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
242a0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
242b0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
242c0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
242d0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
242e0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
242f0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
24300 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
24310 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
24320 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
24330 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
24340 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
24350 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
24360 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
24370 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
24380 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
24390 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
243a0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
243b0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
243c0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
243d0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
243e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
243f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24400 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
24410 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
24420 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
24430 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24440 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
24450 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
24460 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
24470 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
24480 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
24490 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
244a0 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
244b0 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
244c0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
244d0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
244e0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
244f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
24500 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
24510 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
24520 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
24530 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
24540 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
24550 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
24560 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
24570 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24580 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
24590 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
245a0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
245b0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
245c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
245d0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
245e0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
245f0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
24600 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
24610 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
24620 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
24630 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
24640 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
24650 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
24660 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
24670 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
24680 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
24690 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
246a0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
246b0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
246c0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
246d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
246e0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
246f0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
24700 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
24710 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
24720 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
24730 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
24740 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
24750 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
24760 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
24770 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
24780 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
24790 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
247a0 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
247b0 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
247c0 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
247d0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
247e0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
247f0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
24800 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
24810 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
24820 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
24830 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24840 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
24850 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
24860 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24870 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
24880 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
24890 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
248a0 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
248b0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
248c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
248d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
248e0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
248f0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
24900 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
24910 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
24920 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
24930 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
24940 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
24950 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24960 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
24970 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
24980 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
24990 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
249a0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
249b0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
249c0 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
249d0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
249e0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
249f0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
24a00 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
24a10 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
24a20 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
24a30 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
24a40 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
24a50 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
24a60 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
24a70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24a80 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
24a90 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
24aa0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
24ab0 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
24ac0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
24ad0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
24ae0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
24af0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
24b00 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
24b10 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
24b20 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
24b30 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
24b40 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
24b50 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
24b60 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
24b70 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
24b80 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
24b90 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
24ba0 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
24bb0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
24bc0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
24bd0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
24be0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
24bf0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
24c00 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
24c10 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
24c20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
24c30 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
24c40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
24c50 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
24c60 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
24c70 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
24c80 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
24c90 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
24ca0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
24cb0 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
24cc0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
24cd0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
24ce0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
24cf0 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
24d00 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
24d10 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
24d20 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
24d30 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
24d40 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
24d50 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
24d60 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
24d70 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
24d80 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
24d90 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
24da0 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
24db0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
24dc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
24dd0 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
24de0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
24df0 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
24e00 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
24e10 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
24e20 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
24e30 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
24e40 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
24e50 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
24e60 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
24e70 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
24e80 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
24e90 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
24ea0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
24eb0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
24ec0 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
24ed0 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
24ee0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
24ef0 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
24f00 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
24f10 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
24f20 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
24f30 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
24f40 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
24f50 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
24f60 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
24f70 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
24f80 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
24f90 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
24fa0 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
24fb0 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
24fc0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
24fd0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
24fe0 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
24ff0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
25000 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
25010 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
25020 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
25030 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
25040 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
25050 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
25060 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
25070 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
25080 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
25090 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
250a0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
250b0 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
250c0 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
250d0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
250e0 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
250f0 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
25100 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
25110 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
25120 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
25130 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
25140 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
25150 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
25160 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
25170 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
25180 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
25190 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
251a0 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
251b0 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
251c0 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
251d0 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
251e0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
251f0 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
25200 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73   .** ^On windows
25210 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
25220 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
25230 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
25240 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
25250 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
25260 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  ")..**.** [[core
25270 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
25280 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
25290 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
252a0 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
252b0 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
252c0 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
252d0 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
252e0 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
252f0 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
25300 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
25310 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
25320 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
25330 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
25340 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  ree query parame
25350 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
25360 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
25370 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
25380 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
25390 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
253a0 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
253b0 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
253c0 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
253d0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
253e0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
253f0 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
25400 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
25410 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
25420 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
25430 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
25440 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
25450 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25460 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
25470 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
25480 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
25490 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
254a0 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
254b0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
254c0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
254d0 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
254e0 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
254f0 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
25500 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
25510 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
25520 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
25530 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
25540 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
25550 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
25560 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25570 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
25580 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
25590 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
255a0 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
255b0 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
255c0 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
255d0 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
255e0 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
255f0 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
25600 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
25610 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
25620 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
25630 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
25640 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
25650 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
25660 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
25670 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
25680 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
25690 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
256a0 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
256b0 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
256c0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
256d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
256e0 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
256f0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
25700 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
25710 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
25720 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
25730 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
25740 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
25750 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
25760 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
25770 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
25780 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
25790 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
257a0 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
257b0 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
257c0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
257d0 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
257e0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
257f0 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
25800 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
25810 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
25820 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
25830 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
25840 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
25850 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
25860 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
25870 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
25880 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
25890 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
258a0 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
258b0 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
258c0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
258d0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
258e0 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
258f0 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
25900 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
25910 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
25920 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
25930 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25940 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
25950 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
25960 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
25970 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
25980 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
25990 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
259a0 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
259b0 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
259c0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
259d0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
259e0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
259f0 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
25a00 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
25a10 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
25a20 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
25a30 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
25a40 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
25a50 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
25a60 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
25a70 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
25a80 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
25a90 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
25aa0 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
25ab0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
25ac0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
25ad0 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
25ae0 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
25af0 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
25b00 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
25b10 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
25b20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65  any behaviour re
25b30 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
25b40 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
25b50 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
25b60 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
25b70 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
25b80 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  ag..** </ul>.**.
25b90 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
25ba0 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
25bb0 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
25bc0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
25bd0 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
25be0 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
25bf0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
25c00 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
25c10 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
25c20 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
25c30 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
25c40 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
25c50 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
25c60 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
25c70 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
25c80 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
25c90 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
25ca0 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
25cb0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
25cc0 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
25cd0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
25ce0 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
25cf0 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
25d00 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
25d10 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
25d20 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
25d30 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
25d40 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
25d50 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
25d60 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
25d70 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
25d80 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
25d90 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
25da0 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
25db0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
25dc0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
25dd0 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
25de0 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
25df0 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
25e00 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
25e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
25e20 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
25e30 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
25e40 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
25e50 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
25e60 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
25e70 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
25e80 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
25e90 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
25ea0 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
25eb0 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
25ec0 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
25ed0 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
25ee0 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
25ef0 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
25f00 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
25f10 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
25f20 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
25f30 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
25f40 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
25f50 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
25f60 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
25f70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
25f80 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
25f90 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
25fa0 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
25fb0 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
25fc0 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
25fd0 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
25fe0 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
25ff0 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
26000 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
26010 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
26020 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
26030 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
26040 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
26050 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
26060 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
26070 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
26080 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
26090 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
260a0 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
260b0 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
260c0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
260d0 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
260e0 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
260f0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
26100 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
26110 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
26120 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
26130 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
26140 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74  s=unix-nolock <t
26150 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
26160 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
26170 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
26180 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
26190 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22  FS "unix-nolock"
261a0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
261b0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
261c0 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
261d0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
261e0 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
261f0 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
26200 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
26210 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
26220 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
26230 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
26240 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
26250 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
26260 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
26270 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
26280 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
26290 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
262a0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
262b0 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
262c0 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
262d0 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
262e0 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
262f0 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
26300 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
26310 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
26320 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
26330 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
26340 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
26350 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
26360 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
26370 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
26380 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
26390 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
263a0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
263b0 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
263c0 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
263d0 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
263e0 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
263f0 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
26400 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
26410 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
26420 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
26430 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
26440 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
26450 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
26460 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
26470 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
26480 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
26490 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
264a0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
264b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
264c0 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
264d0 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
264e0 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
264f0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
26500 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
26510 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
26520 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
26530 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
26540 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
26550 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
26560 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
26570 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
26580 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
26590 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
265a0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
265b0 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
265c0 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
265d0 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
265e0 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
265f0 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
26600 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
26610 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
26620 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
26630 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
26640 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
26650 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
26660 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
26670 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
26680 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
26690 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53  _directory].*/.S
266a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
266b0 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
266c0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
266d0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
266e0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
266f0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
26700 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
26710 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
26720 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
26730 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
26740 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
26750 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
26760 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
26770 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
26780 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
26790 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
267a0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
267b0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
267c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
267d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
267e0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
267f0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
26800 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
26810 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
26820 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
26830 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
26840 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
26850 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
26860 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
26870 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
26880 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
26890 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
268a0 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
268b0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
268c0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
268d0 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
268e0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
268f0 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
26900 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
26910 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
26920 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
26930 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
26940 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
26950 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
26960 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
26970 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
26980 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
26990 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
269a0 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
269b0 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
269c0 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
269d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
269e0 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
269f0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
26a00 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
26a10 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
26a20 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
26a30 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
26a40 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
26a50 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
26a60 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
26a70 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
26a80 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
26a90 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
26aa0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
26ab0 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
26ac0 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
26ad0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
26ae0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
26af0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
26b00 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
26b10 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
26b20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
26b30 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
26b40 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
26b50 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
26b60 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
26b70 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
26b80 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
26b90 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
26ba0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
26bb0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
26bc0 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
26bd0 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
26be0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
26bf0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
26c00 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
26c10 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
26c20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
26c30 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
26c40 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
26c50 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
26c60 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
26c70 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
26c80 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
26c90 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
26ca0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
26cb0 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
26cc0 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
26cd0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
26ce0 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
26cf0 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
26d00 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
26d10 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
26d20 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
26d30 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
26d40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
26d50 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
26d60 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
26d70 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
26d80 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
26d90 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
26da0 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
26db0 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
26dc0 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
26dd0 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
26de0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
26df0 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
26e00 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
26e10 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
26e20 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
26e30 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
26e40 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
26e50 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
26e60 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
26e70 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
26e80 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
26e90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26ea0 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
26eb0 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
26ec0 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
26ed0 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
26ee0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
26ef0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
26f00 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
26f10 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
26f20 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
26f30 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
26f40 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
26f50 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
26f60 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
26f70 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
26f80 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
26f90 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
26fa0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
26fb0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
26fc0 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
26fd0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
26fe0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
26ff0 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
27000 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
27010 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
27020 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
27030 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
27040 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
27050 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
27060 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
27070 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
27080 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
27090 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
270a0 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
270b0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51  desirable..*/.SQ
270c0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
270d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
270e0 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
270f0 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
27100 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
27110 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50  aram);.SQLITE_AP
27120 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  I int sqlite3_ur
27130 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
27140 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
27150 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
27160 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
27170 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
27180 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
27190 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
271a0 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
271b0 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
271c0 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
271d0 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
271e0 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
271f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27200 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
27210 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
27220 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
27230 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
27240 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
27250 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
27260 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
27270 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
27280 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
27290 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
272a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
272b0 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
272c0 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
272d0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
272e0 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
272f0 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
27300 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
27310 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
27320 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
27330 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
27340 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
27350 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
27360 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
27370 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
27380 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
27390 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
273a0 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
273b0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
273c0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
273d0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
273e0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
273f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
27400 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
27410 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
27420 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
27430 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
27440 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
27450 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
27460 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
27470 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
27480 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27490 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
274a0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
274b0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
274c0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
274d0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
274e0 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
274f0 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
27500 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
27510 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
27520 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
27530 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
27540 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
27550 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
27560 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
27570 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
27580 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
27590 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
275a0 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
275b0 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
275c0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
275d0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
275e0 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
275f0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
27600 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
27610 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
27620 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
27630 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
27640 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
27650 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
27660 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
27670 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
27680 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
27690 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
276a0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
276b0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
276c0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
276d0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
276e0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
276f0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
27700 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
27710 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
27720 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
27730 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
27740 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
27750 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
27760 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
27770 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
27780 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
27790 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
277a0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
277b0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
277c0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
277d0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
277e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
277f0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
27800 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
27810 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
27820 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
27830 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
27840 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
27850 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
27860 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
27870 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
27880 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
27890 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
278a0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
278b0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
278c0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
278d0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
278e0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
278f0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
27900 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
27910 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
27920 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
27930 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
27940 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
27950 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
27960 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
27970 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
27980 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
27990 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  I int sqlite3_er
279a0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
279b0 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  b);.SQLITE_API i
279c0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
279d0 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
279e0 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
279f0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
27a00 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
27a10 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
27a20 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
27a30 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
27a40 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  16(sqlite3*);.SQ
27a50 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
27a60 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
27a70 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
27a80 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
27a90 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
27aa0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
27ab0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27ac0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
27ad0 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
27ae0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
27af0 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
27b00 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
27b10 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
27b20 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
27b30 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
27b40 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
27b50 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
27b60 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
27b70 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
27b80 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
27b90 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
27ba0 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
27bb0 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
27bc0 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
27bd0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
27be0 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
27bf0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
27c00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
27c10 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
27c20 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
27c30 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
27c40 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
27c50 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
27c60 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
27c70 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
27c80 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
27c90 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
27ca0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
27cb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
27cc0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
27cd0 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
27ce0 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
27cf0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
27d00 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
27d10 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
27d20 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
27d30 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
27d40 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
27d50 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
27d60 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
27d70 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
27d80 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
27d90 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
27da0 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
27db0 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
27dc0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
27dd0 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
27de0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
27df0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
27e00 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
27e10 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
27e20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
27e30 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
27e40 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
27e50 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
27e60 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
27e70 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
27e80 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
27e90 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
27ea0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
27eb0 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
27ec0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
27ed0 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
27ee0 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
27ef0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
27f00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
27f10 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
27f20 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
27f30 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
27f40 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
27f50 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
27f60 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
27f70 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
27f80 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
27f90 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
27fa0 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
27fb0 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
27fc0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
27fd0 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
27fe0 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
27ff0 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
28000 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
28010 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
28020 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
28030 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
28040 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
28050 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
28060 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
28070 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
28080 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
28090 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
280a0 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
280b0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
280c0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
280d0 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
280e0 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
280f0 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
28100 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
28110 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
28120 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
28130 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
28140 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
28150 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
28160 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
28170 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
28180 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
28190 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
281a0 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
281b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
281c0 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
281d0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
281e0 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
281f0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
28200 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
28210 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
28220 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
28230 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
28240 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
28250 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
28260 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
28270 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
28280 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
28290 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
282a0 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
282b0 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
282c0 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
282d0 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
282e0 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
282f0 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
28300 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
28310 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
28320 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
28330 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
28340 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
28350 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
28360 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
28370 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
28380 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
28390 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
283a0 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
283b0 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
283c0 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
283d0 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
283e0 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
283f0 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
28400 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
28410 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
28420 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
28430 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
28440 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
28450 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
28460 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
28470 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
28480 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
28490 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
284a0 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
284b0 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
284c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
284d0 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
284e0 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
284f0 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
28500 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
28510 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
28520 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
28530 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
28540 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
28550 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
28560 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
28570 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
28580 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
28590 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
285a0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
285b0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
285c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
285d0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
285e0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
285f0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
28600 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28610 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
28620 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
28630 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
28640 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
28650 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
28660 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
28670 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
28680 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
28690 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
286a0 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
286b0 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
286c0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
286d0 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
286e0 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
286f0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
28700 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
28710 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
28720 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
28730 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
28740 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
28750 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
28760 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
28770 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
28780 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
28790 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
287a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
287b0 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
287c0 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
287d0 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
287e0 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
287f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28800 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
28810 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
28820 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
28830 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
28840 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
28850 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
28860 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
28870 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
28880 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
28890 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
288a0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
288b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
288c0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
288d0 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
288e0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
288f0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
28900 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
28910 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
28920 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
28930 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
28940 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
28950 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
28960 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
28970 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28980 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
28990 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
289a0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
289b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
289c0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
289d0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
289e0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
289f0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
28a00 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
28a10 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
28a20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28a30 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
28a40 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
28a50 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
28a60 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
28a70 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
28a80 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
28a90 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
28aa0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
28ab0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
28ac0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
28ad0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28ae0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
28af0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
28b00 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
28b10 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
28b20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
28b30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
28b40 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
28b50 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
28b60 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
28b70 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
28b80 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
28b90 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
28ba0 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
28bb0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28bc0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
28bd0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
28be0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
28bf0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
28c00 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
28c10 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
28c20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
28c30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
28c40 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
28c50 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
28c60 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
28c70 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
28c80 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
28c90 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
28ca0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
28cb0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
28cc0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
28cd0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
28ce0 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
28cf0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
28d00 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
28d10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
28d20 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
28d30 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
28d40 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
28d50 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
28d60 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
28d70 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
28d80 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
28d90 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
28da0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28db0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
28dc0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
28dd0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
28de0 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
28df0 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
28e00 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
28e10 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28e20 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
28e30 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
28e40 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
28e50 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
28e60 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
28e70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
28e80 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
28e90 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
28ea0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
28eb0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
28ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28ed0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
28ee0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
28ef0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
28f00 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
28f10 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
28f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28f30 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
28f40 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
28f50 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
28f60 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
28f70 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
28f80 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
28f90 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
28fa0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
28fb0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
28fc0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
28fd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
28fe0 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
28ff0 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
29000 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
29010 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
29020 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
29030 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
29040 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
29050 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
29060 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
29070 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
29080 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
29090 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
290a0 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
290b0 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a           10../*.
290c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
290d0 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
290e0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
290f0 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
29100 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
29110 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
29120 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
29130 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
29140 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
29150 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
29160 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
29170 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
29180 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
29190 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
291a0 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
291b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
291c0 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
291d0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
291e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
291f0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
29200 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
29210 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
29220 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
29230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
29240 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
29250 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
29260 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
29270 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
29280 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
29290 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
292a0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
292b0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
292c0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
292d0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
292e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
292f0 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
29300 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
29310 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
29320 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
29330 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
29340 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
29350 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
29360 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
29370 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
29380 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
29390 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
293a0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
293b0 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
293c0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
293d0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
293e0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
293f0 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
29400 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68   from zSql.  ^Wh
29410 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
29420 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
29430 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
29440 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
29450 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
29460 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
29470 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
29480 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
29490 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
294a0 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
294b0 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
294c0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
294d0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
294e0 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
294f0 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
29500 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
29510 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
29520 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
29530 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
29540 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
29550 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
29560 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
29570 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
29580 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
29590 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
295a0 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73  or bytes as this
295b0 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72   saves SQLite fr
295c0 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20  om having to.** 
295d0 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
295e0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
295f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
29600 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
29610 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
29620 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
29630 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
29640 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
29650 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
29660 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
29670 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
29680 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
29690 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
296a0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
296b0 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
296c0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
296d0 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
296e0 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
296f0 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
29700 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
29710 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
29720 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
29730 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
29740 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
29750 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
29760 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
29770 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
29780 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
29790 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
297a0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
297b0 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
297c0 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
297d0 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
297e0 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
297f0 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
29800 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
29810 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
29820 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
29830 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
29840 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
29850 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
29860 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
29870 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
29880 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
29890 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
298a0 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
298b0 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
298c0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
298d0 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
298e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
298f0 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
29900 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
29910 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
29920 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
29930 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29940 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
29950 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
29960 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
29970 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
29980 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
29990 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
299a0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
299b0 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
299c0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
299d0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
299e0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
299f0 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
29a00 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
29a10 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
29a20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
29a30 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
29a40 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
29a50 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
29a60 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
29a70 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
29a80 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
29a90 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
29aa0 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
29ab0 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
29ac0 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
29ad0 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
29ae0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
29af0 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
29b00 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
29b10 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
29b20 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
29b30 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
29b40 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
29b50 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
29b60 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
29b70 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
29b80 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
29b90 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
29ba0 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a  run it again..**
29bb0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
29bc0 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
29bd0 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
29be0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
29bf0 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
29c00 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
29c10 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
29c20 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
29c30 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
29c40 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
29c50 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
29c60 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
29c70 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
29c80 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
29c90 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
29ca0 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
29cb0 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
29cc0 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
29cd0 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
29ce0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
29cf0 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
29d00 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
29d10 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
29d20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
29d30 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
29d40 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
29d50 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
29d60 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
29d70 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
29d80 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
29d90 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
29da0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
29db0 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
29dc0 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
29dd0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
29de0 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
29df0 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
29e00 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
29e10 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
29e20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
29e30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
29e40 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
29e50 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
29e60 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
29e70 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
29e80 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
29e90 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
29ea0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29eb0 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
29ec0 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
29ed0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
29ee0 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
29ef0 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
29f00 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
29f10 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
29f20 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
29f30 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
29f40 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
29f50 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
29f60 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
29f70 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
29f80 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
29f90 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
29fa0 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
29fb0 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
29fc0 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
29fd0 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
29fe0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
29ff0 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
2a000 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
2a010 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
2a020 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65   enabled..** the
2a030 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
2a040 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ol>.*/.SQLITE_AP
2a050 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
2a060 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
2a070 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2a080 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2a090 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2a0a0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2a0b0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2a0c0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2a0d0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2a0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2a0f0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2a100 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2a110 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2a120 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2a130 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2a140 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a150 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2a160 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2a170 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2a180 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2a190 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
2a1a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2a1b0 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
2a1c0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2a1d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2a1e0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2a1f0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2a200 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2a210 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2a220 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2a230 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2a240 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2a250 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2a260 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2a270 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2a280 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2a290 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2a2a0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2a2b0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2a2c0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2a2d0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2a2e0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
2a2f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
2a300 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
2a310 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2a320 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2a330 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2a340 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2a350 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2a360 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2a370 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2a380 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2a390 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2a3a0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2a3b0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2a3c0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2a3d0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2a3e0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2a3f0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2a400 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2a410 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2a420 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2a430 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
2a440 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
2a450 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
2a460 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2a470 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2a480 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2a490 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2a4a0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2a4b0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2a4c0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2a4d0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2a4e0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2a4f0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2a500 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2a510 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2a520 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2a530 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2a540 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2a550 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2a560 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2a570 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2a580 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
2a590 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
2a5a0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
2a5b0 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
2a5c0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2a5d0 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
2a5e0 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
2a5f0 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
2a600 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
2a610 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
2a620 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a630 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
2a640 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
2a650 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
2a660 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a670 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2a680 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2a690 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2a6a0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2a6b0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
2a6c0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2a6d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a6e0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2a6f0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
2a700 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
2a710 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ase.**.** ^The s
2a720 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2a730 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
2a740 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
2a750 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
2a760 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
2a770 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a780 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
2a790 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
2a7a0 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
2a7b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2a7c0 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
2a7d0 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
2a7e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2a7f0 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
2a800 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
2a810 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
2a820 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
2a830 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
2a840 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
2a850 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
2a860 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
2a870 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
2a880 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
2a890 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
2a8a0 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
2a8b0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
2a8c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
2a8d0 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
2a8e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
2a8f0 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
2a900 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
2a910 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
2a920 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
2a930 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
2a940 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
2a950 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2a960 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
2a970 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
2a980 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2a990 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
2a9a0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
2a9b0 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
2a9c0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2a9d0 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
2a9e0 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
2a9f0 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
2aa00 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
2aa10 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
2aa20 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
2aa30 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
2aa40 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
2aa50 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
2aa60 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2aa70 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2aa80 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
2aa90 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
2aaa0 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
2aab0 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
2aac0 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
2aad0 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
2aae0 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
2aaf0 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
2ab00 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
2ab10 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
2ab20 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
2ab30 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
2ab40 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
2ab50 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
2ab60 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2ab70 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
2ab80 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
2ab90 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
2aba0 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
2abb0 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
2abc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2abd0 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
2abe0 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
2abf0 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
2ac00 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2ac10 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
2ac20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2ac30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2ac40 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
2ac50 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2ac60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2ac70 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
2ac80 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2ac90 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
2aca0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2acb0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
2acc0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2acd0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2ace0 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
2acf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ad00 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
2ad10 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
2ad20 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2ad30 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
2ad40 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20   has not run to 
2ad50 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f  completion and/o
2ad60 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65  r has not .** be
2ad70 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
2ad80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2ad90 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2ada0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
2adb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2adc0 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
2add0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2ade0 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
2adf0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2ae00 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
2ae10 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
2ae20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ae30 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
2ae40 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2ae50 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
2ae60 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
2ae70 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
2ae80 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
2ae90 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
2aea0 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
2aeb0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
2aec0 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
2aed0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2aee0 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
2aef0 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
2af00 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
2af10 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
2af20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
2af30 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
2af40 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
2af50 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
2af60 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
2af70 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
2af80 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
2af90 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
2afa0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
2afb0 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
2afc0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
2afd0 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
2afe0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2aff0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
2b000 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
2b010 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
2b020 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
2b030 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
2b040 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
2b050 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
2b060 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2b070 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2b080 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
2b090 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
2b0a0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
2b0b0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
2b0c0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
2b0d0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
2b0e0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
2b0f0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
2b100 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
2b110 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
2b120 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
2b130 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
2b140 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2b150 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
2b160 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
2b170 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
2b180 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
2b190 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
2b1a0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
2b1b0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
2b1c0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2b1d0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
2b1e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2b1f0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
2b200 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
2b210 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
2b220 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
2b230 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b240 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
2b250 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
2b260 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
2b270 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
2b280 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
2b290 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
2b2a0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
2b2b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2b2c0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
2b2d0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
2b2e0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
2b2f0 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
2b300 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
2b310 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
2b320 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
2b330 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
2b340 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2b350 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
2b360 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
2b370 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
2b380 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2b390 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
2b3a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2b3b0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
2b3c0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
2b3d0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
2b3e0 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
2b3f0 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
2b400 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
2b410 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
2b420 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
2b430 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
2b440 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
2b450 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2b460 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
2b470 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2b480 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
2b490 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
2b4a0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2b4b0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2b4c0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2b4d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2b4e0 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
2b4f0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
2b500 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
2b510 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
2b520 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
2b530 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
2b540 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
2b550 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
2b560 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
2b570 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2b580 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2b590 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2b5a0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2b5b0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
2b5c0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
2b5d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2b5e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2b5f0 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
2b600 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
2b610 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
2b620 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2b630 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2b640 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2b650 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
2b660 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
2b670 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b680 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2b690 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2b6a0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
2b6b0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
2b6c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b6d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
2b6e0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2b6f0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
2b700 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
2b710 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2b720 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
2b730 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2b740 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
2b750 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
2b760 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
2b770 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
2b780 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b790 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
2b7a0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2b7b0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
2b7c0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
2b7d0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
2b7e0 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
2b7f0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
2b800 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
2b810 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
2b820 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
2b830 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
2b840 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
2b850 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
2b860 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
2b870 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
2b880 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
2b890 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
2b8a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2b8b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
2b8c0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2b8d0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2b8e0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2b8f0 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
2b900 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
2b910 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
2b920 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
2b930 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
2b940 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
2b950 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
2b960 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
2b970 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2b980 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
2b990 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2b9a0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
2b9b0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2b9c0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
2b9d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2b9e0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
2b9f0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2ba00 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
2ba10 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
2ba20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
2ba30 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
2ba40 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
2ba50 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
2ba60 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
2ba70 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
2ba80 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
2ba90 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
2baa0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
2bab0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
2bac0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
2bad0 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
2bae0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
2baf0 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
2bb00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
2bb10 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
2bb20 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
2bb30 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
2bb40 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
2bb50 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
2bb60 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
2bb70 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
2bb80 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
2bb90 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
2bba0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
2bbb0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
2bbc0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
2bbd0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
2bbe0 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
2bbf0 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
2bc00 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
2bc10 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
2bc20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
2bc30 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
2bc40 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
2bc50 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
2bc60 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
2bc70 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
2bc80 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
2bc90 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
2bca0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
2bcb0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
2bcc0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
2bcd0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2bce0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
2bcf0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2bd00 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
2bd10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2bd20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
2bd30 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
2bd40 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2bd50 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
2bd60 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
2bd70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bd80 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
2bd90 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
2bda0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2bdb0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2bdc0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
2bdd0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
2bde0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
2bdf0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
2be00 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
2be10 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
2be20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
2be30 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
2be40 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
2be50 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2be60 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
2be70 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
2be80 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
2be90 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
2bea0 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
2beb0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
2bec0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
2bed0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
2bee0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2bef0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2bf00 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
2bf10 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
2bf20 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
2bf30 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
2bf40 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
2bf50 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
2bf60 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
2bf70 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
2bf80 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
2bf90 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
2bfa0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2bfb0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
2bfc0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
2bfd0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
2bfe0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
2bff0 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
2c000 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
2c010 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2c020 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2c030 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2c040 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2c050 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2c060 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2c070 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2c080 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2c090 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2c0a0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2c0b0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2c0c0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2c0d0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2c0e0 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2c0f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2c100 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2c110 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2c120 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2c130 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2c140 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2c150 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2c160 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2c170 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2c180 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2c190 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2c1a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2c1b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2c1c0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2c1d0 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2c1e0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2c1f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2c200 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2c210 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2c220 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2c230 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2c240 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2c250 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68  bind_text16() th
2c260 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  en that paramete
2c270 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
2c280 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
2c290 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
2c2a0 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
2c2b0 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
2c2c0 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
2c2d0 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
2c2e0 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
2c2f0 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
2c300 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
2c310 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
2c320 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
2c330 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
2c340 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
2c350 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
2c360 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
2c370 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
2c380 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
2c390 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
2c3a0 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
2c3b0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
2c3c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2c3d0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2c3e0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2c3f0 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
2c400 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2c410 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
2c420 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
2c430 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
2c440 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
2c450 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
2c460 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
2c470 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
2c480 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
2c490 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2c4a0 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
2c4b0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2c4c0 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
2c4d0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71  f the call to sq
2c4e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2c4f0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  ),.** sqlite3_bi
2c500 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71  nd_text(), or sq
2c510 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2c520 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20  6() fails.  .** 
2c530 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2c540 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
2c550 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
2c560 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
2c570 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
2c580 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
2c590 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
2c5a0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
2c5b0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
2c5c0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2c5d0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
2c5e0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2c5f0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
2c600 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
2c610 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
2c620 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
2c630 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2c640 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
2c650 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
2c660 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
2c670 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
2c680 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2c690 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2c6a0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
2c6b0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
2c6c0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
2c6d0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
2c6e0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
2c6f0 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
2c700 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
2c710 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
2c720 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
2c730 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
2c740 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
2c750 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
2c760 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
2c770 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
2c780 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2c790 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
2c7a0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
2c7b0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
2c7c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2c7d0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
2c7e0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
2c7f0 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
2c800 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
2c810 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
2c820 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
2c830 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
2c840 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
2c850 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2c860 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2c870 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
2c880 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
2c890 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2c8a0 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
2c8b0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2c8c0 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
2c8d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2c8e0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
2c8f0 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
2c900 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
2c910 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
2c920 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
2c930 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
2c940 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
2c950 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
2c960 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
2c970 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
2c980 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2c990 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2c9a0 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
2c9b0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
2c9c0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
2c9d0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
2c9e0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
2c9f0 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
2ca00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
2ca10 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
2ca20 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
2ca30 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
2ca40 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
2ca50 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2ca60 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
2ca70 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
2ca80 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
2ca90 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
2caa0 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
2cab0 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
2cac0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
2cad0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
2cae0 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
2caf0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
2cb00 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
2cb10 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2cb20 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
2cb30 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2cb40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2cb50 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2cb60 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2cb70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2cb80 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
2cb90 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2cba0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2cbb0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2cbc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2cbd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2cbe0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2cbf0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
2cc00 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
2cc10 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2cc20 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
2cc30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2cc40 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45   double);.SQLITE
2cc50 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2cc60 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
2cc70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2cc80 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  t);.SQLITE_API i
2cc90 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2cca0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2ccb0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2ccc0 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  3_int64);.SQLITE
2ccd0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2cce0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
2ccf0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2cd00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2cd10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2cd20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2cd30 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
2cd40 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
2cd50 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
2cd60 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2cd70 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
2cd80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2cd90 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2cda0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2cdb0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
2cdc0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2cdd0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2cde0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2cdf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2ce00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ce10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2ce20 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
2ce30 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
2ce40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ce50 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
2ce60 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
2ce70 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
2ce80 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
2ce90 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
2cea0 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
2ceb0 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
2cec0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2ced0 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
2cee0 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
2cef0 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
2cf00 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
2cf10 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
2cf20 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
2cf30 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
2cf40 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
2cf50 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
2cf60 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
2cf70 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
2cf80 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
2cf90 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
2cfa0 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
2cfb0 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
2cfc0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
2cfd0 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
2cfe0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
2cff0 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
2d000 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
2d010 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
2d020 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
2d030 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
2d040 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
2d050 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
2d060 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
2d070 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
2d080 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
2d090 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
2d0a0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2d0b0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2d0c0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2d0d0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2d0e0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
2d0f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2d100 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2d110 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2d120 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2d130 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2d140 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2d150 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2d160 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2d170 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2d180 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d190 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2d1a0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
2d1b0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
2d1c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
2d1d0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
2d1e0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
2d1f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d200 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
2d210 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2d220 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
2d230 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2d240 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
2d250 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
2d260 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
2d270 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2d280 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2d290 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2d2a0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2d2b0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
2d2c0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
2d2d0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
2d2e0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
2d2f0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
2d300 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
2d310 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
2d320 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2d330 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2d340 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2d350 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2d360 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2d370 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2d380 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2d390 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2d3a0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2d3b0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2d3c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2d3d0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2d3e0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2d3f0 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2d400 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2d410 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2d420 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2d430 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2d440 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2d450 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2d460 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2d470 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2d480 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2d490 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2d4a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d4b0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2d4c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2d4d0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2d4e0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2d4f0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2d500 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2d510 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2d520 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2d530 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2d540 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2d550 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2d560 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2d570 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
2d580 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
2d590 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d5a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2d5b0 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
2d5c0 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
2d5d0 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
2d5e0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
2d5f0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
2d600 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
2d610 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
2d620 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
2d630 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
2d640 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
2d650 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
2d660 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2d670 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2d680 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
2d690 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
2d6a0 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
2d6b0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
2d6c0 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
2d6d0 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
2d6e0 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
2d6f0 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
2d700 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
2d710 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
2d720 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
2d730 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
2d740 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2d750 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2d760 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2d770 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2d780 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2d790 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2d7a0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2d7b0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2d7c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2d7d0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2d7e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2d7f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2d800 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
2d810 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
2d820 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
2d830 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2d840 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
2d850 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2d860 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ement.**.** ^Con
2d870 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
2d880 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
2d890 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d8a0 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
2d8b0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2d8c0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
2d8d0 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
2d8e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d8f0 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
2d900 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
2d910 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
2d920 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
2d930 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2d940 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2d950 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2d960 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2d970 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2d980 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
2d990 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
2d9a0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
2d9b0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2d9c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
2d9d0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2d9e0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2d9f0 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
2da00 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2da10 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
2da20 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2da30 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
2da40 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
2da50 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
2da60 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
2da70 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
2da80 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  ta_count()].*/.S
2da90 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2daa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2dab0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2dac0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2dad0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
2dae0 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
2daf0 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
2db00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2db10 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
2db20 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
2db30 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
2db40 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2db50 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2db60 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
2db70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2db80 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
2db90 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2dba0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2dbb0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2dbc0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
2dbd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2dbe0 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
2dbf0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2dc00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2dc10 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2dc20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2dc30 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
2dc40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2dc50 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
2dc60 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
2dc70 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
2dc80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2dc90 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
2dca0 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
2dcb0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2dcc0 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
2dcd0 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
2dce0 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
2dcf0 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
2dd00 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
2dd10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2dd20 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
2dd30 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2dd40 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2dd50 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2dd60 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2dd70 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2dd80 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2dd90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2dda0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2ddb0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2ddc0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
2ddd0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2dde0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
2ddf0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2de00 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
2de10 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
2de20 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
2de30 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
2de40 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
2de50 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
2de60 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
2de70 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
2de80 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
2de90 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
2dea0 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
2deb0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2dec0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2ded0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
2dee0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
2def0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
2df00 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
2df10 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
2df20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
2df30 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
2df40 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
2df50 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
2df60 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
2df70 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
2df80 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
2df90 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
2dfa0 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
2dfb0 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49  he next..*/.SQLI
2dfc0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2dfd0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2dfe0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2dff0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51  tmt*, int N);.SQ
2e000 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2e010 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2e020 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
2e030 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2e040 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e050 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
2e060 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
2e070 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ult.**.** ^These
2e080 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
2e090 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
2e0a0 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
2e0b0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
2e0c0 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
2e0d0 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
2e0e0 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
2e0f0 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
2e100 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
2e110 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
2e120 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
2e130 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
2e140 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
2e150 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
2e160 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
2e170 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2e180 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
2e190 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2e1a0 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
2e1b0 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
2e1c0 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
2e1d0 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
2e1e0 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
2e1f0 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
2e200 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
2e210 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
2e220 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2e230 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2e240 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2e250 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
2e260 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
2e270 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e280 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2e290 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2e2a0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2e2b0 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2e2c0 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2e2d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2e2e0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2e2f0 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2e300 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
2e310 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
2e320 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
2e330 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
2e340 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
2e350 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
2e360 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
2e370 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
2e380 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
2e390 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
2e3a0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
2e3b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2e3c0 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
2e3d0 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
2e3e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2e3f0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2e400 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
2e410 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
2e420 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
2e430 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
2e440 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
2e450 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2e460 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
2e470 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
2e480 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
2e490 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
2e4a0 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
2e4b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
2e4c0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
2e4d0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
2e4e0 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
2e4f0 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
2e500 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
2e510 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
2e520 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
2e530 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2e540 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
2e550 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
2e560 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
2e570 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
2e580 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2e590 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
2e5a0 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
2e5b0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
2e5c0 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
2e5d0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
2e5e0 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
2e5f0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
2e600 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
2e610 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
2e620 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
2e630 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
2e640 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
2e650 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
2e660 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
2e670 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
2e680 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
2e690 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2e6a0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
2e6b0 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
2e6c0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2e6d0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2e6e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2e6f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2e700 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2e710 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2e720 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
2e730 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2e740 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2e750 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
2e760 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
2e770 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
2e780 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e790 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
2e7a0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2e7b0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2e7c0 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
2e7d0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2e7e0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2e7f0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
2e800 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2e810 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
2e820 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
2e830 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
2e840 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
2e850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e860 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
2e870 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
2e880 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2e890 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2e8a0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49  defined..*/.SQLI
2e8b0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2e8c0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2e8d0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
2e8e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2e8f0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2e900 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2e910 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2e920 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
2e930 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2e940 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2e950 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2e960 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
2e970 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2e980 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2e990 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2e9a0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2e9b0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2e9c0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2e9d0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2e9e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2e9f0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
2ea00 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2ea10 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2ea20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2ea30 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2ea40 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2ea50 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2ea60 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
2ea70 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
2ea80 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
2ea90 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
2eaa0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
2eab0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2eac0 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
2ead0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
2eae0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2eaf0 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
2eb00 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
2eb10 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
2eb20 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
2eb30 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
2eb40 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
2eb50 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2eb60 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
2eb70 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
2eb80 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
2eb90 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
2eba0 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
2ebb0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
2ebc0 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
2ebd0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2ebe0 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
2ebf0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2ec00 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
2ec10 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2ec20 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
2ec30 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
2ec40 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2ec50 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
2ec60 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
2ec70 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
2ec80 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
2ec90 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
2eca0 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
2ecb0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2ecc0 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
2ecd0 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
2ece0 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
2ecf0 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
2ed00 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
2ed10 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
2ed20 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
2ed30 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
2ed40 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
2ed50 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
2ed60 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
2ed70 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
2ed80 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
2ed90 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
2eda0 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
2edb0 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
2edc0 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
2edd0 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
2ede0 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
2edf0 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
2ee00 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
2ee10 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
2ee20 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
2ee30 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
2ee40 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
2ee50 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
2ee60 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
2ee70 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
2ee80 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
2ee90 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
2eea0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
2eeb0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
2eec0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
2eed0 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
2eee0 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ues..*/.SQLITE_A
2eef0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2ef00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2ef10 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
2ef20 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2ef30 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2ef40 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2ef50 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
2ef60 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2ef70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ef80 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
2ef90 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2efa0 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2efb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2efc0 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2efd0 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2efe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2eff0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2f000 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2f010 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2f020 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2f030 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2f040 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2f050 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2f060 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2f070 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2f080 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2f090 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2f0a0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2f0b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2f0c0 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2f0d0 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2f0e0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2f0f0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2f100 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2f110 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2f120 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2f130 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2f140 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2f150 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2f160 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f170 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2f180 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2f190 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2f1a0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2f1b0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2f1c0 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2f1d0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2f1e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2f1f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2f200 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2f210 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2f220 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2f230 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2f240 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2f250 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2f260 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2f270 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2f280 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2f290 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2f2a0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2f2b0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2f2c0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2f2d0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2f2e0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2f2f0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2f300 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2f310 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2f320 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2f330 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2f340 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2f350 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2f360 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2f370 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2f380 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2f390 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2f3a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2f3b0 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2f3c0 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2f3d0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2f3e0 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2f3f0 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2f400 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2f410 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2f420 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2f430 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2f440 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2f450 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2f460 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2f470 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2f480 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2f490 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2f4a0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2f4b0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2f4c0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2f4d0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2f4e0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2f4f0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2f500 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2f510 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2f520 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2f530 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2f540 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2f550 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2f560 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2f570 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2f580 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2f590 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2f5a0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2f5b0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2f5c0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2f5d0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2f5e0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2f5f0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2f600 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2f610 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2f620 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2f630 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2f640 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2f650 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2f660 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2f670 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2f680 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2f690 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2f6a0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2f6b0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2f6c0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2f6d0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2f6e0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2f6f0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2f700 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2f710 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2f720 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2f730 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2f740 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2f750 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2f760 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2f770 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2f780 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2f790 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2f7a0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2f7b0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2f7c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2f7d0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2f7e0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2f7f0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2f800 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2f810 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2f820 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2f830 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2f840 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2f850 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2f860 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2f870 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2f880 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2f890 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2f8a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f8b0 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2f8c0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2f8d0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2f8e0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2f8f0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2f900 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2f910 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2f920 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2f930 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2f940 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2f950 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2f960 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2f970 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2f980 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2f990 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2f9a0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2f9b0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2f9c0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2f9d0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2f9e0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2f9f0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2fa00 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2fa10 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2fa20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2fa30 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2fa40 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2fa50 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2fa60 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2fa70 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2fa80 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2fa90 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2faa0 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2fab0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2fac0 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2fad0 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2fae0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2faf0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2fb00 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2fb10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2fb20 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2fb30 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2fb40 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2fb50 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2fb60 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2fb70 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2fb80 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2fb90 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2fba0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2fbb0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2fbc0 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2fbd0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2fbe0 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2fbf0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2fc00 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2fc10 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2fc20 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2fc30 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2fc40 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2fc50 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2fc60 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2fc70 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2fc80 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2fc90 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2fca0 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2fcb0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2fcc0 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2fcd0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2fce0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2fcf0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2fd00 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2fd10 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2fd20 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2fd30 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2fd40 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2fd50 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2fd60 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2fd70 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2fd80 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2fd90 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2fda0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2fdb0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2fdc0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2fdd0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2fde0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2fdf0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2fe00 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2fe10 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2fe20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2fe30 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2fe40 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2fe50 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2fe60 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2fe70 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2fe80 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2fe90 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2fea0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2feb0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2fec0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2fed0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2fee0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2fef0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2ff00 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2ff10 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2ff20 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2ff30 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2ff40 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2ff50 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2ff60 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2ff70 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2ff80 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2ff90 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2ffa0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2ffb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ffc0 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2ffd0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2ffe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2fff0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
30000 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
30010 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
30020 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
30030 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
30040 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
30050 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
30060 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
30070 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
30080 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
30090 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
300a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
300b0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
300c0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
300d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
300e0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
300f0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
30100 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30110 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
30120 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30130 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
30140 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
30150 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
30160 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
30170 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
30180 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
30190 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
301a0 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
301b0 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
301c0 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
301d0 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
301e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
301f0 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
30200 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
30210 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
30220 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
30230 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
30240 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
30250 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
30260 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
30270 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
30280 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
30290 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
302a0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
302b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
302c0 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
302d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
302e0 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
302f0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
30300 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
30310 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
30320 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
30330 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
30340 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
30350 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
30360 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
30370 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
30380 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
30390 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
303a0 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
303b0 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
303c0 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
303d0 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
303e0 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
303f0 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
30400 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
30410 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
30420 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
30430 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
30440 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
30450 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
30460 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
30470 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
30480 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
30490 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
304a0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
304b0 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
304c0 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
304d0 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
304e0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
304f0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
30500 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
30510 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
30520 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
30530 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
30540 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
30550 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
30560 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
30570 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
30580 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
30590 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
305a0 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
305b0 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
305c0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
305d0 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
305e0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
305f0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
30600 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
30610 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
30620 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
30630 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
30640 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
30650 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
30660 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
30670 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
30680 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
30690 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
306a0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
306b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
306c0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
306d0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
306e0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
306f0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
30700 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
30710 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
30720 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
30730 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
30740 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
30750 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
30760 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
30770 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
30780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30790 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
307a0 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
307b0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
307c0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
307d0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
307e0 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
307f0 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
30800 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
30810 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
30820 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
30830 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
30840 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
30850 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
30860 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
30870 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
30880 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
30890 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
308a0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
308b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
308c0 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
308d0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
308e0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
308f0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
30900 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
30910 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
30920 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
30930 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
30940 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
30950 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
30960 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
30970 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
30980 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
30990 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
309a0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
309b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
309c0 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
309d0 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
309e0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
309f0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
30a00 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
30a10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
30a20 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
30a30 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
30a40 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
30a50 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
30a60 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
30a70 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
30a80 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
30a90 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
30aa0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
30ab0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
30ac0 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
30ad0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
30ae0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
30af0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
30b00 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
30b10 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
30b20 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
30b30 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
30b40 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
30b50 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
30b60 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
30b70 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
30b80 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
30b90 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
30ba0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
30bb0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
30bc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
30bd0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
30be0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
30bf0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
30c00 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
30c10 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
30c20 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
30c30 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
30c40 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
30c50 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
30c60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
30c70 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
30c80 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
30c90 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
30ca0 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
30cb0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
30cc0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
30cd0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
30ce0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
30cf0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
30d00 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
30d10 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
30d20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
30d30 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
30d40 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
30d50 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
30d60 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
30d70 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
30d80 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
30d90 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
30da0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
30db0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
30dc0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
30dd0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
30de0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
30df0 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
30e00 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
30e10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30e20 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
30e30 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
30e40 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
30e50 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
30e60 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
30e70 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
30e80 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
30e90 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
30ea0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
30eb0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
30ec0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
30ed0 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
30ee0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
30ef0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
30f00 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
30f10 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
30f20 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
30f30 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
30f40 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
30f50 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
30f60 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
30f70 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
30f80 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
30f90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
30fa0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
30fb0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
30fc0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
30fd0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
30fe0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
30ff0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
31000 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
31010 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
31020 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
31030 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
31040 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
31050 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
31060 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
31070 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
31080 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31090 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
310a0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
310b0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
310c0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
310d0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
310e0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
310f0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
31100 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
31110 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31120 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
31130 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
31140 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
31150 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
31160 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
31170 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
31180 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
31190 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
311a0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
311b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
311c0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
311d0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
311e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
311f0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
31200 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
31210 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
31220 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
31230 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
31240 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
31250 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
31260 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
31270 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31280 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
31290 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
312a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
312b0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
312c0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
312d0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
312e0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
312f0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
31300 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
31310 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
31320 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
31330 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
31340 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
31350 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
31360 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
31370 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
31380 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
31390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
313a0 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
313b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
313c0 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
313d0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
313e0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
313f0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
31400 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
31410 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
31420 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
31430 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
31440 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
31450 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31460 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
31470 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
31480 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
31490 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
314a0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
314b0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
314c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
314d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
314e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
314f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
31500 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
31510 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
31520 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
31530 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
31540 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
31550 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
31560 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
31570 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
31580 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
31590 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
315a0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
315b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
315c0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
315d0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
315e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
315f0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
31600 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
31610 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
31620 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
31630 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
31640 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
31650 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
31660 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
31670 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
31680 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31690 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
316a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
316b0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
316c0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
316d0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
316e0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
316f0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
31700 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
31710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31720 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
31730 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
31740 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
31750 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
31760 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
31770 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
31780 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
31790 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
317a0 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
317b0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
317c0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
317d0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
317e0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
317f0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
31800 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
31810 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
31820 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
31830 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
31840 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
31850 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
31860 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
31870 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
31880 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
31890 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
318a0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
318b0 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
318c0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
318d0 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
318e0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
318f0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
31900 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
31910 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
31920 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
31930 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
31940 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
31950 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
31960 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
31970 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
31980 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
31990 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
319a0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
319b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
319c0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
319d0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
319e0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
319f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
31a00 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
31a10 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
31a20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
31a30 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
31a40 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
31a50 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
31a60 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
31a70 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
31a80 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
31a90 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
31aa0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
31ab0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
31ac0 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
31ad0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
31ae0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
31af0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
31b00 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
31b10 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
31b20 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
31b30 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
31b40 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
31b50 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
31b60 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
31b70 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
31b80 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
31b90 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
31ba0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
31bb0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
31bc0 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
31bd0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
31be0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
31bf0 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
31c00 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
31c10 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
31c20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
31c30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
31c40 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
31c50 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
31c60 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
31c70 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
31c80 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
31c90 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
31ca0 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
31cb0 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
31cc0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
31cd0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
31ce0 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
31cf0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
31d00 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
31d10 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
31d20 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
31d30 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
31d40 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
31d50 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
31d60 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
31d70 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
31d80 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
31d90 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
31da0 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
31db0 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
31dc0 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
31dd0 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
31de0 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
31df0 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
31e00 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
31e10 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
31e20 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
31e30 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
31e40 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
31e50 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
31e60 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
31e70 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
31e80 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
31e90 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
31ea0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
31eb0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
31ec0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
31ed0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
31ee0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
31ef0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
31f00 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
31f10 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
31f20 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
31f30 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
31f40 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
31f50 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
31f60 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
31f70 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
31f80 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
31f90 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
31fa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31fb0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
31fc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31fd0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
31fe0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
31ff0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
32000 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
32010 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
32020 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
32030 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
32040 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
32050 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
32060 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32070 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
32080 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
32090 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
320a0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
320b0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
320c0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
320d0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
320e0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
320f0 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
32100 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
32110 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
32120 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
32130 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
32140 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
32150 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
32160 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
32170 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
32180 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
32190 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
321a0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
321b0 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
321c0 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
321d0 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
321e0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
321f0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
32200 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
32210 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
32220 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
32230 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
32240 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
32250 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
32260 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
32270 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
32280 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
32290 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
322a0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
322b0 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
322c0 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
322d0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
322e0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
322f0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
32300 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
32310 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
32320 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
32330 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
32340 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
32350 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
32360 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
32370 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
32380 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
32390 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
323a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
323b0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
323c0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
323d0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
323e0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
323f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32400 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
32410 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32420 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
32430 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
32440 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
32450 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
32460 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
32470 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
32480 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32490 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
324a0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
324b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
324c0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
324d0 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
324e0 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
324f0 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
32500 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
32510 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32520 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
32530 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
32540 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
32550 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
32560 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
32570 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
32580 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
32590 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
325a0 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
325b0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
325c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
325d0 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
325e0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
325f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32600 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
32610 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
32620 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
32630 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
32640 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
32650 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
32660 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
32670 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
32680 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
32690 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
326a0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
326b0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
326c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
326d0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
326e0 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
326f0 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
32700 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
32710 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
32720 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
32730 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
32740 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
32750 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
32760 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
32770 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
32780 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
32790 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
327a0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
327b0 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
327c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
327d0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
327e0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
327f0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
32800 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
32810 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
32820 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
32830 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
32840 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
32850 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
32860 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
32870 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
32880 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
32890 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
328a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
328b0 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
328c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
328d0 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  M].)^.*/.SQLITE_
328e0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
328f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32900 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
32910 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
32920 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
32930 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32940 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
32950 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
32960 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
32970 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
32980 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
32990 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
329a0 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71  TE_API double sq
329b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
329c0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
329d0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
329e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
329f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
32a00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
32a10 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
32a20 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
32a30 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
32a40 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
32a50 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
32a60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
32a70 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
32a80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
32a90 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
32aa0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
32ab0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
32ac0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
32ad0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
32ae0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
32af0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
32b00 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
32b10 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
32b20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
32b30 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
32b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
32b50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
32b60 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
32b70 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
32b80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
32b90 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
32ba0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
32bb0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
32bc0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
32bd0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
32be0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
32bf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32c00 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
32c10 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
32c20 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
32c30 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
32c40 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
32c50 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
32c60 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
32c70 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
32c80 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
32c90 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
32ca0 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
32cb0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
32cc0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
32cd0 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
32ce0 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
32cf0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
32d00 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
32d10 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
32d20 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
32d30 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
32d40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32d50 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
32d60 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
32d70 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
32d80 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
32d90 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
32da0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32db0 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
32dc0 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
32dd0 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
32de0 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
32df0 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
32e00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
32e10 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
32e20 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
32e30 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
32e40 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
32e50 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
32e60 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
32e70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
32e80 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
32e90 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
32ea0 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
32eb0 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
32ec0 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
32ed0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
32ee0 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
32ef0 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
32f00 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
32f10 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
32f20 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
32f30 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
32f40 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
32f50 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
32f60 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
32f70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32f80 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
32f90 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
32fa0 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
32fb0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
32fc0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
32fd0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
32fe0 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
32ff0 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
33000 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
33010 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
33020 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
33030 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  ruption..*/.SQLI
33040 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
33050 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
33060 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
33070 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33080 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
33090 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
330a0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ject.**.** The s
330b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
330c0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
330d0 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72  d to reset a [pr
330e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
330f0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b  ].** object back
33100 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
33110 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
33120 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
33130 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74  ** ^Any SQL stat
33140 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
33150 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
33160 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
33170 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
33180 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
33190 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
331a0 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
331b0 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
331c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
331d0 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
331e0 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
331f0 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  gs..**.** ^The [
33200 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
33210 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
33220 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
33230 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
33240 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
33250 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
33260 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ogram..**.** ^If
33270 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
33280 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
33290 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
332a0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
332b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
332c0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
332d0 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
332e0 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73  NE],.** or if [s
332f0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
33300 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
33310 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
33320 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  S,.** then [sqli
33330 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
33340 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
33350 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
33360 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
33370 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
33380 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
33390 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
333a0 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74  ement] S indicat
333b0 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65  ed an error, the
333c0 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  n.** [sqlite3_re
333d0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
333e0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
333f0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
33400 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
33410 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
33420 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
33430 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
33440 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74  ** of any [sqlit
33450 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
33460 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
33470 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33480 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  t] S..*/.SQLITE_
33490 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
334a0 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
334b0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
334c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
334d0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
334e0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
334f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
33500 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
33510 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
33520 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
33530 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
33540 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
33550 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
33560 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
33570 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
33580 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
33590 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
335a0 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
335b0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
335c0 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
335d0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
335e0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
335f0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
33600 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
33610 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
33620 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
33630 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
33640 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
33650 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
33660 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
33670 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
33680 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
33690 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
336a0 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
336b0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
336c0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
336d0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
336e0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
336f0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
33700 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
33710 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
33720 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
33730 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
33740 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
33750 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33760 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
33770 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
33780 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
33790 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
337a0 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
337b0 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
337c0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
337d0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
337e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
337f0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
33800 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
33810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33820 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
33830 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
33840 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
33850 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
33860 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
33870 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
33880 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
33890 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
338a0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
338b0 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
338c0 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
338d0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
338e0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
338f0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
33900 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
33910 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
33920 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
33930 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
33940 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
33950 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
33960 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
33970 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
33980 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
33990 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
339a0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
339b0 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
339c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
339d0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
339e0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
339f0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
33a00 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
33a10 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
33a20 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
33a30 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
33a40 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
33a50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
33a60 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
33a70 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
33a80 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
33a90 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
33aa0 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
33ab0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
33ac0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
33ad0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
33ae0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
33af0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
33b00 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
33b10 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
33b20 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
33b30 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
33b40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
33b50 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
33b60 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
33b70 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
33b80 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
33b90 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
33ba0 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
33bb0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
33bc0 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20  ameters.  Every 
33bd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
33be0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
33bf0 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
33c00 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20  .** with UTF-8, 
33c10 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
33c20 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
33c30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
33c40 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
33c50 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
33c60 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
33c70 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
33c80 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
33c90 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
33ca0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33cb0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
33cc0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
33cd0 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
33ce0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
33cf0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
33d00 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
33d10 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
33d20 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
33d30 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
33d40 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
33d50 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
33d60 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
33d70 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
33d80 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
33d90 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
33da0 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
33db0 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
33dc0 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
33dd0 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
33de0 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
33df0 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
33e00 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
33e10 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
33e20 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
33e30 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
33e40 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
33e50 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
33e60 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
33e70 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
33e80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33e90 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
33ea0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
33eb0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
33ec0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
33ed0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
33ee0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
33ef0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
33f00 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
33f10 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
33f20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
33f30 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
33f40 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
33f50 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
33f60 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
33f70 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
33f80 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
33f90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
33fa0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
33fb0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
33fc0 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
33fd0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
33fe0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
33ff0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
34000 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
34010 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
34020 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
34030 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
34040 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34050 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
34060 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
34070 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
34080 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
34090 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
340a0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
340b0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
340c0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
340d0 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
340e0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
340f0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
34100 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
34110 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
34120 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34130 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
34140 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
34150 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
34160 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
34170 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
34180 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
34190 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
341a0 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
341b0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
341c0 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
341d0 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
341e0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
341f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34200 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
34210 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
34220 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
34230 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
34240 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
34250 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
34260 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
34270 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
34280 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
34290 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
342a0 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
342b0 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
342c0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
342d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
342e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
342f0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
34300 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
34310 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
34320 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
34330 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
34340 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
34350 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
34360 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
34370 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
34380 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
34390 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
343a0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
343b0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
343c0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
343d0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
343e0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
343f0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
34400 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
34410 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
34420 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
34430 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
34440 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
34450 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
34460 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
34470 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
34480 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
34490 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
344a0 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
344b0 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
344c0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
344d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
344e0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
344f0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
34500 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
34510 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
34520 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
34530 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
34540 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
34550 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
34560 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
34570 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
34580 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
34590 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
345a0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
345b0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
345c0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
345d0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
345e0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
345f0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
34600 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
34610 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
34620 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
34630 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
34640 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
34650 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
34660 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
34670 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34680 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
34690 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
346a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
346b0 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
346c0 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
346d0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
346e0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
346f0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
34700 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
34710 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
34720 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
34730 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
34740 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
34750 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
34760 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
34770 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
34780 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
34790 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
347a0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
347b0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
347c0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
347d0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
347e0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
347f0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
34800 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
34810 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
34820 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
34830 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
34840 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34850 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
34860 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
34870 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
34880 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51  _context*).);.SQ
34890 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
348a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
348b0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
348c0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
348d0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
348e0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
348f0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
34900 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
34910 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
34920 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
34930 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
34940 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
34950 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
34960 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
34970 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
34980 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
34990 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
349a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
349b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
349c0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
349d0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
349e0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
349f0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
34a00 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
34a10 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
34a20 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
34a30 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
34a40 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
34a50 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
34a60 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
34a70 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
34a80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
34a90 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
34aa0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
34ab0 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
34ac0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
34ad0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34ae0 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
34af0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
34b00 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
34b10 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
34b20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
34b30 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
34b40 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
34b50 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
34b60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
34b70 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
34b80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
34b90 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
34ba0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
34bb0 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
34bc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
34bd0 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
34be0 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
34bf0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
34c00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
34c10 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
34c20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
34c30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
34c40 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
34c50 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
34c60 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
34c70 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34c80 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
34c90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
34ca0 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
34cb0 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
34cc0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
34cd0 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
34ce0 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
34cf0 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
34d00 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
34d10 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
34d20 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
34d30 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
34d40 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
34d50 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
34d60 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
34d70 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
34d80 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
34d90 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
34da0 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
34db0 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
34dc0 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
34dd0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
34de0 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
34df0 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68  tell you what th
34e00 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
34e10 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
34e20 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
34e30 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
34e40 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
34e50 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
34e60 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
34e70 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
34e80 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
34e90 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
34ea0 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
34eb0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  mt*);.SQLITE_API
34ec0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
34ed0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
34ee0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
34ef0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
34f00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
34f10 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
34f20 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
34f30 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
34f40 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
34f50 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
34f60 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
34f70 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
34f80 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
34f90 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
34fa0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
34fb0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
34fc0 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
34fd0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
34fe0 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69  ,int),void*,sqli
34ff0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
35000 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
35010 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
35020 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
35030 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a  eter Values.**.*
35040 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
35050 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35060 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
35070 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
35080 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
35090 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
350a0 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
350b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
350c0 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
350d0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
350e0 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
350f0 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
35100 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
35110 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
35120 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
35130 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
35140 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35150 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
35160 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35170 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
35180 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
35190 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
351a0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
351b0 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
351c0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
351d0 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
351e0 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
351f0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
35200 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
35210 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
35220 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
35230 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
35240 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
35250 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
35260 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
35270 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
35280 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
35290 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
352a0 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
352b0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
352c0 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
352d0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
352e0 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
352f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35300 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
35310 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
35320 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
35330 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
35340 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35350 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
35360 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
35370 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
35380 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
35390 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
353a0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
353b0 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
353c0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
353d0 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65  except that  the
353e0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
353f0 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
35400 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
35410 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
35420 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
35430 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
35440 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
35450 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
35460 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
35470 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
35480 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
35490 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
354a0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
354b0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
354c0 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
354d0 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
354e0 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
354f0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
35500 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
35510 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
35520 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
35530 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
35540 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
35550 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
35560 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
35570 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
35580 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
35590 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
355a0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
355b0 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
355c0 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
355d0 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
355e0 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
355f0 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
35600 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
35610 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
35620 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
35630 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
35640 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
35650 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
35660 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
35670 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
35680 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
35690 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
356a0 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
356b0 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
356c0 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
356d0 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
356e0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
356f0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
35700 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
35710 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
35720 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
35730 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
35740 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
35750 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
35760 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
35770 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
35780 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
35790 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
357a0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
357b0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
357c0 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
357d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
357e0 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
357f0 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
35800 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
35810 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
35820 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
35830 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
35840 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
35850 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
35860 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
35870 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
35880 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
35890 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
358a0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
358b0 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
358c0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
358d0 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
358e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
358f0 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
35900 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
35910 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
35920 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
35930 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
35940 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
35950 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
35960 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
35970 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
35980 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
35990 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
359a0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
359b0 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69  _API double sqli
359c0 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
359d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
359e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
359f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
35a00 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
35a10 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
35a20 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
35a30 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
35a40 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
35a50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
35a60 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
35a70 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
35a80 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
35a90 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
35aa0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
35ab0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
35ac0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
35ad0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
35ae0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
35af0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
35b00 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
35b10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
35b20 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
35b30 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
35b40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
35b50 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
35b60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
35b70 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
35b80 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
35b90 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
35ba0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
35bb0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
35bc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35bd0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
35be0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
35bf0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
35c00 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
35c10 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
35c20 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
35c30 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
35c40 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
35c50 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
35c60 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
35c70 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
35c80 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
35c90 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
35ca0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
35cb0 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
35cc0 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
35cd0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
35ce0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
35cf0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
35d00 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
35d10 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
35d20 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
35d30 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
35d40 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
35d50 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
35d60 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
35d70 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
35d80 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
35d90 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
35da0 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
35db0 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
35dc0 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
35dd0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
35de0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
35df0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
35e00 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
35e10 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
35e20 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
35e30 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
35e40 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
35e50 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
35e60 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
35e70 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
35e80 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
35e90 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
35ea0 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
35eb0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
35ec0 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
35ed0 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
35ee0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
35ef0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
35f00 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
35f10 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
35f20 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
35f30 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
35f40 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
35f50 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
35f60 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
35f70 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
35f80 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
35f90 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
35fa0 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
35fb0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
35fc0 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
35fd0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
35fe0 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
35ff0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
36000 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
36010 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
36020 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
36030 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
36040 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
36050 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
36060 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
36070 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
36080 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
36090 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
360a0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
360b0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
360c0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
360d0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
360e0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
360f0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
36100 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
36110 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
36120 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
36130 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
36140 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
36150 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
36160 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
36170 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
36180 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
36190 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
361a0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
361b0 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
361c0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
361d0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
361e0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
361f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
36200 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
36210 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
36220 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
36230 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
36240 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
36250 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
36260 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
36270 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
36280 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
36290 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
362a0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
362b0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
362c0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
362d0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
362e0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
362f0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
36300 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61   void *sqlite3_a
36310 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
36320 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36330 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
36340 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36350 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
36360 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
36370 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
36380 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
36390 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
363a0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
363b0 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
363c0 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
363d0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
363e0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
363f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
36400 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
36410 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
36420 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
36430 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
36440 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
36450 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
36460 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
36470 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
36480 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
36490 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
364a0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
364b0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
364c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
364d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
364e0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
364f0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
36500 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
36510 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
36520 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
36530 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
36540 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
36550 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
36560 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
36570 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
36580 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36590 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
365a0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
365b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
365c0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
365d0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
365e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
365f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
36600 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
36610 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36620 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
36630 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
36640 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
36650 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
36660 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
36670 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
36680 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
36690 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
366a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
366b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
366c0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
366d0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
366e0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
366f0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
36700 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
36710 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
36720 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
36730 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
36740 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
36750 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
36760 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
36770 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
36780 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
36790 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
367a0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
367b0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
367c0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
367d0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
367e0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
367f0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
36800 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
36810 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
36820 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
36830 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
36840 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
36850 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
36860 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
36870 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
36880 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
36890 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
368a0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
368b0 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
368c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
368d0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
368e0 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
368f0 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
36900 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
36910 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
36920 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
36930 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
36940 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
36950 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
36960 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
36970 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
36980 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
36990 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
369a0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
369b0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
369c0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
369d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
369e0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
369f0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
36a00 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
36a10 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
36a20 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
36a30 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
36a40 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
36a50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36a60 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e   function. ^If n
36a70 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
36a80 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
36a90 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
36aa0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
36ab0 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
36ac0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
36ad0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
36ae0 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
36af0 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
36b00 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
36b10 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
36b20 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
36b30 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
36b40 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
36b50 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
36b60 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
36b70 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
36b80 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
36b90 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
36ba0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
36bb0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
36bc0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
36bd0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
36be0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36bf0 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
36c00 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
36c10 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
36c20 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
36c30 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
36c40 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
36c50 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
36c60 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   ^If it is not N
36c70 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
36c80 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
36c90 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
36ca0 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
36cb0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
36cc0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
36cd0 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
36ce0 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
36cf0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
36d00 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
36d10 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
36d20 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
36d30 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
36d40 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
36d50 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
36d60 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
36d70 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
36d80 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
36d90 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
36da0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
36db0 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
36dc0 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  any time.  ^The 
36dd0 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
36de0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
36df0 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
36e00 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
36e10 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
36e20 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ropped..**.** ^(
36e30 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
36e40 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
36e50 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
36e60 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
36e70 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
36e80 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
36e90 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
36ea0 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
36eb0 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
36ec0 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
36ed0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
36ee0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
36ef0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
36f00 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
36f10 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
36f20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
36f30 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
36f40 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
36f50 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
36f60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36f70 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
36f80 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
36f90 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
36fa0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36fb0 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
36fc0 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
36fd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36fe0 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
36ff0 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
37000 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
37010 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
37020 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
37030 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
37040 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
37050 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
37060 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
37070 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
37080 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
37090 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
370a0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
370b0 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
370c0 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
370d0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
370e0 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
370f0 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
37100 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
37110 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
37120 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
37130 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
37140 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
37150 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
37160 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
37170 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
37180 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
37190 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
371a0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
371b0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
371c0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
371d0 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
371e0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
371f0 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
37200 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
37210 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
37220 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
37230 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
37240 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
37250 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
37260 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
37270 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
37280 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
37290 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
372a0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
372b0 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
372c0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
372d0 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
372e0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
372f0 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
37300 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
37310 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
37320 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
37330 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
37340 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
37350 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
37360 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
37370 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
37380 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
37390 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
373a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
373b0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
373c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
373d0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
373e0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
373f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
37400 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
37410 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
37420 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
37430 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
37440 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
37450 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
37460 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
37470 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
37480 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
37490 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
374a0 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
374b0 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
374c0 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
374d0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
374e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
374f0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
37500 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
37510 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
37520 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
37530 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
37540 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
37550 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
37560 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
37570 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
37580 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
37590 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
375a0 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
375b0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
375c0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
375d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
375e0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
375f0 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
37600 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
37610 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37620 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
37630 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
37640 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
37650 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
37660 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
37670 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
37680 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
37690 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
376a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
376b0 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
376c0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
376d0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
376e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
376f0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37700 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
37710 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
37720 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
37730 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
37740 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37750 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
37760 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37770 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
37780 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
37790 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
377a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
377b0 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
377c0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
377d0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
377e0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
377f0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
37800 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37810 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
37820 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
37830 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
37840 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
37850 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
37860 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
37870 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
37880 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
37890 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
378a0 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
378b0 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
378c0 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
378d0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
378e0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
378f0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
37900 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
37910 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
37920 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37930 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37940 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
37950 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
37960 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
37970 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
37980 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
37990 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
379a0 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
379b0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
379c0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
379d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
379e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
379f0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
37a00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37a10 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
37a20 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
37a30 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
37a40 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
37a50 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
37a60 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
37a70 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
37a80 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
37a90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37aa0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
37ab0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37ac0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
37ad0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
37ae0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
37af0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
37b00 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
37b10 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
37b20 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
37b30 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
37b40 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
37b50 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
37b60 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
37b70 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
37b80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37b90 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
37ba0 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
37bb0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
37bc0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
37bd0 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
37be0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
37bf0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
37c00 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
37c10 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
37c20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
37c30 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
37c40 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
37c50 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
37c60 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
37c70 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
37c80 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
37c90 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
37ca0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37cb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37cc0 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  r_toobig() inter
37cd0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
37ce0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
37cf0 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
37d00 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
37d10 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
37d20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
37d30 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
37d40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37d50 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  or_nomem() inter
37d60 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
37d70 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
37d80 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
37d90 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
37da0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
37db0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
37dc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
37dd0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
37de0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
37df0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
37e00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37e10 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37e20 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
37e30 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
37e40 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
37e50 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
37e60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
37e70 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
37e80 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
37e90 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
37ea0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
37eb0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37ec0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
37ed0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
37ee0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
37ef0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
37f00 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
37f10 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37f20 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
37f30 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
37f40 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
37f50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37f60 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37f70 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
37f80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37f90 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
37fa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37fb0 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
37fc0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37fd0 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
37fe0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
37ff0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
38000 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
38010 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
38020 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
38030 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
38040 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
38050 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
38060 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
38070 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
38080 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
38090 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
380a0 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
380b0 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
380c0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
380d0 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
380e0 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
380f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
38100 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
38110 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
38120 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
38130 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
38140 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
38150 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
38160 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
38170 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
38180 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
38190 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
381a0 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
381b0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
381c0 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
381d0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
381e0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
381f0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
38200 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
38210 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
38220 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
38230 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
38240 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
38250 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
38260 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
38270 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
38280 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38290 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
382a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
382b0 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
382c0 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68  n result.  If th
382d0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
382e0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
382f0 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74   then it.** must
38300 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
38310 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72  set into the str
38320 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55  ing where the NU
38330 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
38340 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20  ld.** appear if 
38350 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
38360 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e   NUL terminated.
38370 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
38380 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a  racters occur.**
38390 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61   in the string a
383a0 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20  t a byte offset 
383b0 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61  that is less tha
383c0 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
383d0 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65  he 3rd.** parame
383e0 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ter, then the re
383f0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77  sulting string w
38400 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  ill contain embe
38410 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68  dded NULs and th
38420 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65  e.** result of e
38430 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61  xpressions opera
38440 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20  ting on strings 
38450 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
38460 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
38470 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
38480 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
38490 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
384a0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
384b0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
384c0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
384d0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
384e0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
384f0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
38500 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
38510 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
38520 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
38530 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
38540 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
38550 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
38560 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
38570 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
38580 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
38590 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
385a0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
385b0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
385c0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
385d0 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
385e0 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
385f0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
38600 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
38610 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
38620 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
38630 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
38640 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
38650 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
38660 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
38670 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
38680 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
38690 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
386a0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
386b0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
386c0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
386d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
386e0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
386f0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
38700 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
38710 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
38720 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
38730 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
38740 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
38750 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
38760 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
38770 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
38780 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
38790 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
387a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sq