System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact e61f743cea8e8b17d7606331051e9887266ae9ba:


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 31 2e 20 20  ersion 3.7.11.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e  atic.#endif.#ifn
0550: 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23  def SQLITE_API.#
0560: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41   define SQLITE_A
0570: 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a  PI.#endif./*****
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20  ********* Begin 
0590: 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68  file sqliteInt.h
05a0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20  ********/./*.** 
05d0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31  2001 September 1
05e0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  5.**.** The auth
05f0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70  or disclaims cop
0600: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73  yright to this s
0610: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20  ource code.  In 
0620: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65  place of.** a le
0630: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65  gal notice, here
0640: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a   is a blessing:.
0650: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  **.**    May you
0660: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74   do good and not
0670: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79   evil..**    May
0680: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76   you find forgiv
0690: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65  eness for yourse
06a0: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f  lf and forgive o
06b0: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79  thers..**    May
06c0: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c   you share freel
06d0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20  y, never taking 
06e0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69  more than you gi
06f0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ve..**.*********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0740: 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74  .** Internal int
0750: 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f  erface definitio
0760: 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a  ns for SQLite..*
0770: 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51  *.*/.#ifndef _SQ
0780: 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69  LITEINT_H_.#defi
0790: 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f  ne _SQLITEINT_H_
07a0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64  ../*.** These #d
07b0: 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e  efines should en
07c0: 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73  able >2GB file s
07d0: 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20  upport on POSIX 
07e0: 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  if the.** underl
07f0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
0800: 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69  ystem supports i
0810: 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61  t.  If the OS la
0820: 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c  cks.** large fil
0830: 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66  e support, or if
0840: 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f   the OS is windo
0850: 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64  ws, these should
0860: 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   be no-ops..**.*
0870: 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20  * Ticket #2739: 
0880: 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f   The _LARGEFILE_
0890: 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73  SOURCE macro mus
08a0: 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20  t appear before 
08b0: 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69  any.** system #i
08c0: 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c  ncludes.  Hence,
08d0: 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63   this block of c
08e0: 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20  ode must be the 
08f0: 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f  very first.** co
0900: 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65  de in all source
0910: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61   files..**.** La
0920: 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74  rge file support
0930: 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64   can be disabled
0940: 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c   using the -DSQL
0950: 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20  ITE_DISABLE_LFS 
0960: 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65  switch.** on the
0970: 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e   compiler comman
0980: 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73  d line.  This is
0990: 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f   necessary if yo
09a0: 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a  u are compiling.
09b0: 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d  ** on a recent m
09c0: 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20  achine (ex: Red 
09d0: 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75  Hat 7.2) but you
09e0: 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20   want your code 
09f0: 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e  to work.** on an
0a00: 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28   older machine (
0a10: 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29  ex: Red Hat 6.0)
0a20: 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c  .  If you compil
0a30: 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32  e on Red Hat 7.2
0a40: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73  .** without this
0a50: 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20   option, LFS is 
0a60: 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53  enable.  But LFS
0a70: 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20   does not exist 
0a80: 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a  in the kernel.**
0a90: 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c   in Red Hat 6.0,
0aa0: 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e   so the code won
0ab0: 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c  't work.  Hence,
0ac0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e   for maximum bin
0ad0: 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69  ary.** portabili
0ae0: 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d  ty you should om
0af0: 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 69  it LFS..**.** Si
0b00: 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f  milar is true fo
0b10: 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53  r Mac OS X.  LFS
0b20: 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74   is only support
0b30: 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39  ed on Mac OS X 9
0b40: 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23   and later..*/.#
0b50: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49  ifndef SQLITE_DI
0b60: 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69  SABLE_LFS.# defi
0b70: 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20  ne _LARGE_FILE  
0b80: 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20       1.# ifndef 
0b90: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54  _FILE_OFFSET_BIT
0ba0: 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49  S.#   define _FI
0bb0: 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36  LE_OFFSET_BITS 6
0bc0: 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69  4.# endif.# defi
0bd0: 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f  ne _LARGEFILE_SO
0be0: 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f  URCE 1.#endif../
0bf0: 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65  *.** Include the
0c00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 68   configuration h
0c10: 65 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 20  eader output by 
0c20: 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 77  'configure' if w
0c30: 65 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  e're using the.*
0c40: 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 64  * autoconf-based
0c50: 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 66   build.*/.#ifdef
0c60: 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 4f   _HAVE_SQLITE_CO
0c70: 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 20  NFIG_H.#include 
0c80: 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 69  "config.h".#endi
0c90: 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  f../************
0ca0: 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74  ** Include sqlit
0cb0: 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 20  eLimit.h in the 
0cc0: 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65  middle of sqlite
0cd0: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  Int.h **********
0ce0: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
0cf0: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71  ** Begin file sq
0d00: 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a  liteLimit.h ****
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d30: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d 61  */./*.** 2007 Ma
0d40: 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  y 7.**.** The au
0d50: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
0d60: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
0d70: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
0d80: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0d90: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0da0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0db0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0dc0: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0dd0: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0de0: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0df0: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0e00: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0e10: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0e20: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
0e30: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
0e40: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
0e50: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ea0: 2a 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 66  **.** .** This f
0eb0: 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 69  ile defines vari
0ec0: 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 68  ous limits of wh
0ed0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 72  at SQLite can pr
0ee0: 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ocess..*/../*.**
0ef0: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   The maximum len
0f00: 67 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f 72  gth of a TEXT or
0f10: 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 20   BLOB in bytes. 
0f20: 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 6c    This also.** l
0f30: 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f  imits the size o
0f40: 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 62  f a row in a tab
0f50: 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a 0a  le or index..**.
0f60: 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d 69  ** The hard limi
0f70: 74 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 79  t is the ability
0f80: 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
0f90: 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 74  ned integer.** t
0fa0: 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a 65  o count the size
0fb0: 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 37  : 2^31-1 or 2147
0fc0: 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 64  483647..*/.#ifnd
0fd0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  ef SQLITE_MAX_LE
0fe0: 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51  NGTH.# define SQ
0ff0: 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 20  LITE_MAX_LENGTH 
1000: 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 69  1000000000.#endi
1010: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 73  f../*.** This is
1020: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1030: 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 20  ber of.**.**    
1040: 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  * Columns in a t
1050: 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c  able.**    * Col
1060: 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
1070: 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e 73  .**    * Columns
1080: 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 20   in a view.**   
1090: 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20   * Terms in the 
10a0: 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 6e  SET clause of an
10b0: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
10c0: 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20  t.**    * Terms 
10d0: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
10e0: 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
10f0: 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a 20  atement.**    * 
1100: 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 4f  Terms in the GRO
1110: 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 42  UP BY or ORDER B
1120: 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 53  Y clauses of a S
1130: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1140: 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69  .**    * Terms i
1150: 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61  n the VALUES cla
1160: 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54  use of an INSERT
1170: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
1180: 20 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20   The hard upper 
1190: 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 32  limit here is 32
11a0: 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 62  676.  Most datab
11b0: 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c 0a  ase people will.
11c0: 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 74  ** tell you that
11d0: 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d 61   in a well-norma
11e0: 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c 20  lized database, 
11f0: 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f 75  you usually shou
1200: 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 6d  ld.** not have m
1210: 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 6e  ore than a dozen
1220: 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 69   or so columns i
1230: 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 6e  n any table.  An
1240: 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 20  d if.** that is 
1250: 74 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 20  the case, there 
1260: 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 68  is no point in h
1270: 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aving more than 
1280: 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 76  a few.** dozen v
1290: 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 20  alues in any of 
12a0: 74 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 74  the other situat
12b0: 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61  ions described a
12c0: 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  bove..*/.#ifndef
12d0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55   SQLITE_MAX_COLU
12e0: 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  MN.# define SQLI
12f0: 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 30  TE_MAX_COLUMN 20
1300: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1310: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   The maximum len
1320: 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  gth of a single 
1330: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1340: 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 74   bytes..**.** It
1350: 20 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20   used to be the 
1360: 63 61 73 65 20 74 68 61 74 20 73 65 74 74 69 6e  case that settin
1370: 67 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f 20  g this value to 
1380: 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 75  zero would.** tu
1390: 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 66  rn the limit off
13a0: 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c 6f  .  That is no lo
13b0: 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 69  nger true.  It i
13c0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a 2a  s not possible.*
13d0: 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 6c  * to turn this l
13e0: 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 66  imit off..*/.#if
13f0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1400: 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 66  SQL_LENGTH.# def
1410: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53  ine SQLITE_MAX_S
1420: 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 30  QL_LENGTH 100000
1430: 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  0000.#endif../*.
1440: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  ** The maximum d
1450: 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 65  epth of an expre
1460: 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 73  ssion tree. This
1470: 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 0a   is limited to .
1480: 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62  ** some extent b
1490: 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c  y SQLITE_MAX_SQL
14a0: 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f 6d  _LENGTH. But som
14b0: 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 20  etime you might 
14c0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 63  .** want to plac
14d0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c 69  e more severe li
14e0: 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  mits on the comp
14f0: 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a 2a  lexity of an .**
1500: 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a 0a   expression..**.
1510: 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20  ** A value of 0 
1520: 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 61  used to mean tha
1530: 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
1540: 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a 2a  not enforced..**
1550: 20 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f 20   But that is no 
1560: 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 68  longer true.  Th
1570: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 73  e limit is now s
1580: 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 64  trictly enforced
1590: 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 73  .** at all times
15a0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
15b0: 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50  ITE_MAX_EXPR_DEP
15c0: 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  TH.# define SQLI
15d0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54  TE_MAX_EXPR_DEPT
15e0: 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f  H 1000.#endif../
15f0: 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d  *.** The maximum
1600: 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
1610: 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
1620: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1630: 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 6e  .** The code gen
1640: 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 6f  erator for compo
1650: 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1660: 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a 2a  ments does one.*
1670: 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 72  * level of recur
1680: 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 65  sion for each te
1690: 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 65  rm.  A stack ove
16a0: 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c 74  rflow can result
16b0: 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 65  .** if the numbe
16c0: 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 6f  r of terms is to
16d0: 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 61  o large.  In pra
16e0: 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c 0a  ctice, most SQL.
16f0: 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f 72  ** never has mor
1700: 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 65  e than 3 or 4 te
1710: 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c 75  rms.  Use a valu
1720: 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 6c  e of 0 to disabl
1730: 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 6f  e.** any limit o
1740: 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
1750: 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1760: 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a 23  unt SELECT..*/.#
1770: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41  ifndef SQLITE_MA
1780: 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  X_COMPOUND_SELEC
1790: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  T.# define SQLIT
17a0: 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53  E_MAX_COMPOUND_S
17b0: 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 66  ELECT 500.#endif
17c0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69  ../*.** The maxi
17d0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70  mum number of op
17e0: 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 20  codes in a VDBE 
17f0: 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 20  program..** Not 
1800: 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 63  currently enforc
1810: 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  ed..*/.#ifndef S
1820: 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f  QLITE_MAX_VDBE_O
1830: 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  P.# define SQLIT
1840: 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 35  E_MAX_VDBE_OP 25
1850: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  000.#endif../*.*
1860: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  * The maximum nu
1870: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
1880: 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e 63  s to an SQL func
1890: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  tion..*/.#ifndef
18a0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43   SQLITE_MAX_FUNC
18b0: 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 6e  TION_ARG.# defin
18c0: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e  e SQLITE_MAX_FUN
18d0: 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 65  CTION_ARG 127.#e
18e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  ndif../*.** The 
18f0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1900: 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 65  f in-memory page
1910: 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65  s to use for the
1920: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a 2a   main database.*
1930: 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 20  * table and for 
1940: 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 73  temporary tables
1950: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45  .  The SQLITE_DE
1960: 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45  FAULT_CACHE_SIZE
1970: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
1980: 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 45  TE_DEFAULT_CACHE
1990: 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53  _SIZE.# define S
19a0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41  QLITE_DEFAULT_CA
19b0: 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a 23  CHE_SIZE  2000.#
19c0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
19d0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 4d  LITE_DEFAULT_TEM
19e0: 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 64  P_CACHE_SIZE.# d
19f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
1a00: 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 5f  AULT_TEMP_CACHE_
1a10: 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 66  SIZE  500.#endif
1a20: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ../*.** The defa
1a30: 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 72  ult number of fr
1a40: 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c 61  ames to accumula
1a50: 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69  te in the log fi
1a60: 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 65  le before.** che
1a70: 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 64  ckpointing the d
1a80: 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d  atabase in WAL m
1a90: 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ode..*/.#ifndef 
1aa0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57  SQLITE_DEFAULT_W
1ab0: 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e  AL_AUTOCHECKPOIN
1ac0: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  T.# define SQLIT
1ad0: 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55  E_DEFAULT_WAL_AU
1ae0: 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 30  TOCHECKPOINT  10
1af0: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1b00: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   The maximum num
1b10: 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20  ber of attached 
1b20: 64 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 73  databases.  This
1b30: 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
1b40: 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 54   0.** and 62.  T
1b50: 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  he upper bound o
1b60: 6e 20 36 32 20 69 73 20 62 65 63 61 75 73 65 20  n 62 is because 
1b70: 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  a 64-bit integer
1b80: 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 73   bitmap.** is us
1b90: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
1ba0: 20 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 20   track attached 
1bb0: 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 69  databases..*/.#i
1bc0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1bd0: 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 69  _ATTACHED.# defi
1be0: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54  ne SQLITE_MAX_AT
1bf0: 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 66  TACHED 10.#endif
1c00: 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78  .../*.** The max
1c10: 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 20  imum value of a 
1c20: 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 68  ?nnn wildcard th
1c30: 61 74 20 74 68 65 20 70 61 72 73 65 72 20 77 69  at the parser wi
1c40: 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 69  ll accept..*/.#i
1c50: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1c60: 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1c70: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1c80: 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
1c90: 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 0a  MBER 999.#endif.
1ca0: 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 65  ./* Maximum page
1cb0: 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 65   size.  The uppe
1cc0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 20  r bound on this 
1cd0: 76 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e 20  value is 65536. 
1ce0: 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a 2a   This a limit.**
1cf0: 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 20   imposed by the 
1d00: 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f 66  use of 16-bit of
1d10: 66 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 63  fsets within eac
1d20: 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 61  h page..**.** Ea
1d30: 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  rlier versions o
1d40: 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 64  f SQLite allowed
1d50: 20 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 61   the user to cha
1d60: 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 61  nge this value a
1d70: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t.** compile tim
1d80: 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c 6f  e. This is no lo
1d90: 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c 20  nger permitted, 
1da0: 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 74  on the grounds t
1db0: 68 61 74 20 69 74 20 63 72 65 61 74 65 73 0a 2a  hat it creates.*
1dc0: 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 74  * a library that
1dd0: 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 20   is technically 
1de0: 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 74  incompatible wit
1df0: 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 72  h an SQLite libr
1e00: 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  ary .** compiled
1e10: 20 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e   with a differen
1e20: 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 72  t limit. If a pr
1e30: 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 20  ocess operating 
1e40: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  on a database .*
1e50: 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 69  * with a page-si
1e60: 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 65  ze of 65536 byte
1e70: 73 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e 20  s crashes, then 
1e80: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 53  an instance of S
1e90: 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 6c  QLite .** compil
1ea0: 65 64 20 77 69 74 68 20 74 68 65 20 64 65 66 61  ed with the defa
1eb0: 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c 69  ult page-size li
1ec0: 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  mit will not be 
1ed0: 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b  able to rollback
1ee0: 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 64   .** the aborted
1ef0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
1f00: 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 6f  is could lead to
1f10: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
1f20: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  tion..*/.#ifdef 
1f30: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
1f40: 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 4c  SIZE.# undef SQL
1f50: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a  ITE_MAX_PAGE_SIZ
1f60: 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  E.#endif.#define
1f70: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45   SQLITE_MAX_PAGE
1f80: 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f 2a  _SIZE 65536.../*
1f90: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
1fa0: 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 61  size of a databa
1fb0: 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 6e  se page..*/.#ifn
1fc0: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55  def SQLITE_DEFAU
1fd0: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64  LT_PAGE_SIZE.# d
1fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
1ff0: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 31  AULT_PAGE_SIZE 1
2000: 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 53  024.#endif.#if S
2010: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41  QLITE_DEFAULT_PA
2020: 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f 4d  GE_SIZE>SQLITE_M
2030: 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 75  AX_PAGE_SIZE.# u
2040: 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41  ndef SQLITE_DEFA
2050: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20  ULT_PAGE_SIZE.# 
2060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
2070: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20  FAULT_PAGE_SIZE 
2080: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
2090: 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  SIZE.#endif../*.
20a0: 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 69  ** Ordinarily, i
20b0: 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 78  f no value is ex
20c0: 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 65  plicitly provide
20d0: 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 65  d, SQLite create
20e0: 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 77  s databases.** w
20f0: 69 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 51  ith page size SQ
2100: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47  LITE_DEFAULT_PAG
2110: 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 2c  E_SIZE. However,
2120: 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 69   based on certai
2130: 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 72  n.** device char
2140: 61 63 74 65 72 69 73 74 69 63 73 20 28 73 65 63  acteristics (sec
2150: 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 6f  tor-size and ato
2160: 6d 69 63 20 77 72 69 74 65 28 29 20 73 75 70 70  mic write() supp
2170: 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  ort),.** SQLite 
2180: 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 72  may choose a lar
2190: 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 20  ger value. This 
21a0: 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 20  constant is the 
21b0: 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a 2a  maximum value.**
21c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 6f   SQLite will cho
21d0: 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e 0a  ose on its own..
21e0: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
21f0: 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41  E_MAX_DEFAULT_PA
2200: 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65  GE_SIZE.# define
2210: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41   SQLITE_MAX_DEFA
2220: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 31  ULT_PAGE_SIZE 81
2230: 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51  92.#endif.#if SQ
2240: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54  LITE_MAX_DEFAULT
2250: 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54  _PAGE_SIZE>SQLIT
2260: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a  E_MAX_PAGE_SIZE.
2270: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  # undef SQLITE_M
2280: 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f  AX_DEFAULT_PAGE_
2290: 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51  SIZE.# define SQ
22a0: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54  LITE_MAX_DEFAULT
22b0: 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 54  _PAGE_SIZE SQLIT
22c0: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a  E_MAX_PAGE_SIZE.
22d0: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 4d  #endif.../*.** M
22e0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
22f0: 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 61   pages in one da
2300: 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
2310: 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c 6c  ** This is reall
2320: 79 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 75  y just the defau
2330: 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
2340: 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20   max_page_count 
2350: 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 20  pragma..** This 
2360: 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f 77  value can be low
2370: 65 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 29  ered (or raised)
2380: 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
2390: 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 6d  ng that the.** m
23a0: 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d 61  ax_page_count ma
23b0: 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  cro..*/.#ifndef 
23c0: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
23d0: 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 53  COUNT.# define S
23e0: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43  QLITE_MAX_PAGE_C
23f0: 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 0a  OUNT 1073741823.
2400: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61  #endif../*.** Ma
2410: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 6e  ximum length (in
2420: 20 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 70   bytes) of the p
2430: 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b 45  attern in a LIKE
2440: 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 72   or GLOB.** oper
2450: 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  ator..*/.#ifndef
2460: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45   SQLITE_MAX_LIKE
2470: 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 0a  _PATTERN_LENGTH.
2480: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2490: 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MAX_LIKE_PATTERN
24a0: 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 65  _LENGTH 50000.#e
24b0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 69  ndif../*.** Maxi
24c0: 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
24d0: 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
24e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 6c  ers..**.** A val
24f0: 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 68  ue of 1 means th
2500: 61 74 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  at a trigger pro
2510: 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 65  gram will not be
2520: 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 0a   able to itself.
2530: 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 67  ** fire any trig
2540: 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f 66  gers. A value of
2550: 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f   0 means that no
2560: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
2570: 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 79  s at all .** may
2580: 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a 2f   be executed..*/
2590: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
25a0: 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MAX_TRIGGER_DEPT
25b0: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  H.# define SQLIT
25c0: 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45  E_MAX_TRIGGER_DE
25d0: 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a  PTH 1000.#endif.
25e0: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
25f0: 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c 69   End of sqliteLi
2600: 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  mit.h **********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
2630: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
2640: 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72   Continuing wher
2650: 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e  e we left off in
2660: 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a   sqliteInt.h ***
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
2680: 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 69  ../* Disable nui
2690: 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 6f  sance warnings o
26a0: 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 6c  n Borland compil
26b0: 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e  ers */.#if defin
26c0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
26d0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 72  .#pragma warn -r
26e0: 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 6c  ch /* unreachabl
26f0: 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 6d  e code */.#pragm
2700: 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 43  a warn -ccc /* C
2710: 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 61  ondition is alwa
2720: 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65  ys true or false
2730: 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 6e   */.#pragma warn
2740: 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e 65   -aus /* Assigne
2750: 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 72  d value is never
2760: 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d 61   used */.#pragma
2770: 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 6f   warn -csu /* Co
2780: 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 61  mparing signed a
2790: 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a 23  nd unsigned */.#
27a0: 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 61  pragma warn -spa
27b0: 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 70   /* Suspicious p
27c0: 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 69  ointer arithmeti
27d0: 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20  c */.#endif../* 
27e0: 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f  Needed for vario
27f0: 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e  us definitions..
2800: 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 4e  . */.#ifndef _GN
2810: 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 6e  U_SOURCE.# defin
2820: 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65  e _GNU_SOURCE.#e
2830: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c  ndif../*.** Incl
2840: 75 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61  ude standard hea
2850: 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63  der files as nec
2860: 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66  essary.*/.#ifdef
2870: 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23   HAVE_STDINT_H.#
2880: 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e  include <stdint.
2890: 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66  h>.#endif.#ifdef
28a0: 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48   HAVE_INTTYPES_H
28b0: 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79  .#include <intty
28c0: 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f  pes.h>.#endif../
28d0: 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
28e0: 6e 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  ng macros are us
28f0: 65 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74  ed to cast point
2900: 65 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20  ers to integers 
2910: 61 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  and.** integers 
2920: 74 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68  to pointers.  Th
2930: 65 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69  e way you do thi
2940: 73 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  s varies from on
2950: 65 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f  e compiler.** to
2960: 20 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65   the next, so we
2970: 20 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20   have developed 
2980: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65  the following se
2990: 74 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65  t of #if stateme
29a0: 6e 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61  nts.** to genera
29b0: 74 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d  te appropriate m
29c0: 61 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65  acros for a wide
29d0: 20 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c   range of compil
29e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ers..**.** The c
29f0: 6f 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 61  orrect "ANSI" wa
2a00: 79 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20  y to do this is 
2a10: 74 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 74  to use the intpt
2a20: 72 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e  r_t type. .** Un
2a30: 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61  fortunately, tha
2a40: 74 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74  t typedef is not
2a50: 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c   available on al
2a60: 6c 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a  l compilers, or.
2a70: 2a 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 69  ** if it is avai
2a80: 6c 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72  lable, it requir
2a90: 65 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f  es an #include o
2aa0: 66 20 73 70 65 63 69 66 69 63 20 68 65 61 64 65  f specific heade
2ab0: 72 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20  rs.** that vary 
2ac0: 66 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65  from one machine
2ad0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a   to the next..**
2ae0: 0a 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30  .** Ticket #3860
2af0: 3a 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d  :  The llvm-gcc-
2b00: 34 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f  4.2 compiler fro
2b10: 6d 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f  m Apple chokes o
2b20: 6e 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a  n.** the ((void*
2b30: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29  )&((char*)0)[X])
2b40: 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74   construct.  But
2b50: 20 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20   MSVC chokes on 
2b60: 28 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a  ((void*)(X))..**
2b70: 20 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64   So we have to d
2b80: 65 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73  efine the macros
2b90: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61   in different wa
2ba0: 79 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ys depending on 
2bb0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e  the.** compiler.
2bc0: 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28  .*/.#if defined(
2bd0: 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f  __PTRDIFF_TYPE__
2be0: 29 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20  )  /* This case 
2bf0: 73 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20  should work for 
2c00: 47 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20  GCC */.# define 
2c10: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54  SQLITE_INT_TO_PT
2c20: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f  R(X)  ((void*)(_
2c30: 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29  _PTRDIFF_TYPE__)
2c40: 28 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51  (X)).# define SQ
2c50: 4c 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28  LITE_PTR_TO_INT(
2c60: 58 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52  X)  ((int)(__PTR
2c70: 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29  DIFF_TYPE__)(X))
2c80: 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28  .#elif !defined(
2c90: 5f 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20  __GNUC__)       
2ca0: 2f 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d  /* Works for com
2cb0: 70 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61  pilers other tha
2cc0: 6e 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69  n LLVM */.# defi
2cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f  ne SQLITE_INT_TO
2ce0: 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a  _PTR(X)  ((void*
2cf0: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29  )&((char*)0)[X])
2d00: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2d10: 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20  _PTR_TO_INT(X)  
2d20: 28 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58  ((int)(((char*)X
2d30: 29 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c  )-(char*)0)).#el
2d40: 69 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f  if defined(HAVE_
2d50: 53 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55  STDINT_H)   /* U
2d60: 73 65 20 74 68 69 73 20 63 61 73 65 20 69 66 20  se this case if 
2d70: 77 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 61  we have ANSI hea
2d80: 64 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65  ders */.# define
2d90: 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50   SQLITE_INT_TO_P
2da0: 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28  TR(X)  ((void*)(
2db0: 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20  intptr_t)(X)).# 
2dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54  define SQLITE_PT
2dd0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69  R_TO_INT(X)  ((i
2de0: 6e 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29  nt)(intptr_t)(X)
2df0: 29 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 20  ).#else         
2e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e10: 20 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20   /* Generates a 
2e20: 77 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74  warning - but it
2e30: 20 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f   always works */
2e40: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2e50: 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20  _INT_TO_PTR(X)  
2e60: 28 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64  ((void*)(X)).# d
2e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52  efine SQLITE_PTR
2e80: 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e  _TO_INT(X)  ((in
2e90: 74 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f  t)(X)).#endif../
2ea0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
2eb0: 54 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f  THREADSAFE macro
2ec0: 20 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 64   must be defined
2ed0: 20 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a   as 0, 1, or 2..
2ee0: 2a 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78  ** 0 means mutex
2ef0: 65 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74  es are permanent
2f00: 6c 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74  ly disable and t
2f10: 68 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65  he library is ne
2f20: 76 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66  ver.** threadsaf
2f30: 65 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20  e.  1 means the 
2f40: 6c 69 62 72 61 72 79 20 69 73 20 73 65 72 69 61  library is seria
2f50: 6c 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 74  lized which is t
2f60: 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65  he highest.** le
2f70: 76 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66  vel of threadsaf
2f80: 65 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68  ety.  2 means th
2f90: 65 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c 74  e libary is mult
2fa0: 69 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74  ithreaded - mult
2fb0: 69 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20  iple.** threads 
2fc0: 63 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61  can use SQLite a
2fd0: 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
2fe0: 20 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20   threads try to 
2ff0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
3000: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3010: 69 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  ion at the same 
3020: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65  time..**.** Olde
3030: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
3040: 4c 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74  Lite used an opt
3050: 69 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45  ional THREADSAFE
3060: 20 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75   macro..** We su
3070: 70 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c  pport that for l
3080: 65 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64  egacy..*/.#if !d
3090: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48  efined(SQLITE_TH
30a0: 52 45 41 44 53 41 46 45 29 0a 23 69 66 20 64 65  READSAFE).#if de
30b0: 66 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45  fined(THREADSAFE
30c0: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  ).# define SQLIT
30d0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 54 48 52  E_THREADSAFE THR
30e0: 45 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23 20  EADSAFE.#else.# 
30f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 48  define SQLITE_TH
3100: 52 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49 4d  READSAFE 1 /* IM
3110: 50 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30 39  P: R-07272-22309
3120: 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69   */.#endif.#endi
3130: 66 0a 0a 2f 2a 0a 2a 2a 20 50 6f 77 65 72 73 61  f../*.** Powersa
3140: 66 65 20 6f 76 65 72 77 72 69 74 65 20 69 73 20  fe overwrite is 
3150: 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
3160: 42 75 74 20 63 61 6e 20 62 65 20 74 75 72 6e 65  But can be turne
3170: 64 20 6f 66 66 20 75 73 69 6e 67 0a 2a 2a 20 74  d off using.** t
3180: 68 65 20 2d 44 53 51 4c 49 54 45 5f 50 4f 57 45  he -DSQLITE_POWE
3190: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 3d  RSAFE_OVERWRITE=
31a0: 30 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 6f  0 command-line o
31b0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ption..*/.#ifnde
31c0: 66 20 53 51 4c 49 54 45 5f 50 4f 57 45 52 53 41  f SQLITE_POWERSA
31d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 0a 23 20 64  FE_OVERWRITE.# d
31e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 4f 57  efine SQLITE_POW
31f0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
3200: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a   1.#endif../*.**
3210: 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46 41   The SQLITE_DEFA
3220: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 20 6d 61  ULT_MEMSTATUS ma
3230: 63 72 6f 20 6d 75 73 74 20 62 65 20 64 65 66 69  cro must be defi
3240: 6e 65 64 20 61 73 20 65 69 74 68 65 72 20 30 20  ned as either 0 
3250: 6f 72 20 31 2e 0a 2a 2a 20 49 74 20 64 65 74 65  or 1..** It dete
3260: 72 6d 69 6e 65 73 20 77 68 65 74 68 65 72 20 6f  rmines whether o
3270: 72 20 6e 6f 74 20 74 68 65 20 66 65 61 74 75 72  r not the featur
3280: 65 73 20 72 65 6c 61 74 65 64 20 74 6f 20 0a 2a  es related to .*
3290: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
32a0: 4d 45 4d 53 54 41 54 55 53 20 61 72 65 20 61 76  MEMSTATUS are av
32b0: 61 69 6c 61 62 6c 65 20 62 79 20 64 65 66 61 75  ailable by defau
32c0: 6c 74 20 6f 72 20 6e 6f 74 2e 20 54 68 69 73 20  lt or not. This 
32d0: 76 61 6c 75 65 20 63 61 6e 0a 2a 2a 20 62 65 20  value can.** be 
32e0: 6f 76 65 72 72 69 64 64 65 6e 20 61 74 20 72 75  overridden at ru
32f0: 6e 74 69 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ntime using the 
3300: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
3310: 20 41 50 49 2e 0a 2a 2f 0a 23 69 66 20 21 64 65   API..*/.#if !de
3320: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 46  fined(SQLITE_DEF
3330: 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 29 0a  AULT_MEMSTATUS).
3340: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
3350: 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
3360: 53 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  S 1.#endif../*.*
3370: 2a 20 45 78 61 63 74 6c 79 20 6f 6e 65 20 6f 66  * Exactly one of
3380: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d   the following m
3390: 61 63 72 6f 73 20 6d 75 73 74 20 62 65 20 64 65  acros must be de
33a0: 66 69 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  fined in order t
33b0: 6f 0a 2a 2a 20 73 70 65 63 69 66 79 20 77 68 69  o.** specify whi
33c0: 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ch memory alloca
33d0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 74  tion subsystem t
33e0: 6f 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 20 20 20  o use..**.**    
33f0: 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d   SQLITE_SYSTEM_M
3400: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 20 2f  ALLOC          /
3410: 2f 20 55 73 65 20 6e 6f 72 6d 61 6c 20 73 79 73  / Use normal sys
3420: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 20  tem malloc().** 
3430: 20 20 20 20 53 51 4c 49 54 45 5f 57 49 4e 33 32      SQLITE_WIN32
3440: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20  _MALLOC         
3450: 20 20 2f 2f 20 55 73 65 20 57 69 6e 33 32 20 6e    // Use Win32 n
3460: 61 74 69 76 65 20 68 65 61 70 20 41 50 49 0a 2a  ative heap API.*
3470: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4d 45 4d  *     SQLITE_MEM
3480: 44 45 42 55 47 20 20 20 20 20 20 20 20 20 20 20  DEBUG           
3490: 20 20 20 20 2f 2f 20 44 65 62 75 67 67 69 6e 67      // Debugging
34a0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 79 73 74   version of syst
34b0: 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a 2a  em malloc().**.*
34c0: 2a 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69 66  * On Windows, if
34d0: 20 74 68 65 20 53 51 4c 49 54 45 5f 57 49 4e 33   the SQLITE_WIN3
34e0: 32 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41 54  2_MALLOC_VALIDAT
34f0: 45 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e  E macro is defin
3500: 65 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61 73  ed and the.** as
3510: 73 65 72 74 28 29 20 6d 61 63 72 6f 20 69 73 20  sert() macro is 
3520: 65 6e 61 62 6c 65 64 2c 20 65 61 63 68 20 63 61  enabled, each ca
3530: 6c 6c 20 69 6e 74 6f 20 74 68 65 20 57 69 6e 33  ll into the Win3
3540: 32 20 6e 61 74 69 76 65 20 68 65 61 70 20 73 75  2 native heap su
3550: 62 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c 20  bsystem.** will 
3560: 63 61 75 73 65 20 48 65 61 70 56 61 6c 69 64 61  cause HeapValida
3570: 74 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e  te to be called.
3580: 20 20 49 66 20 68 65 61 70 20 76 61 6c 69 64 61    If heap valida
3590: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69 6c  tion should fail
35a0: 2c 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69 6f  , an.** assertio
35b0: 6e 20 77 69 6c 6c 20 62 65 20 74 72 69 67 67 65  n will be trigge
35c0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74  red..**.** (Hist
35d0: 6f 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54 68  orical note:  Th
35e0: 65 72 65 20 75 73 65 64 20 74 6f 20 62 65 20 73  ere used to be s
35f0: 65 76 65 72 61 6c 20 6f 74 68 65 72 20 6f 70 74  everal other opt
3600: 69 6f 6e 73 2c 20 62 75 74 20 77 65 27 76 65 0a  ions, but we've.
3610: 2a 2a 20 70 61 72 65 64 20 69 74 20 64 6f 77 6e  ** pared it down
3620: 20 74 6f 20 6a 75 73 74 20 74 68 65 73 65 20 74   to just these t
3630: 68 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66 20  hree.).**.** If 
3640: 6e 6f 6e 65 20 6f 66 20 74 68 65 20 61 62 6f 76  none of the abov
3650: 65 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  e are defined, t
3660: 68 65 6e 20 73 65 74 20 53 51 4c 49 54 45 5f 53  hen set SQLITE_S
3670: 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73 0a  YSTEM_MALLOC as.
3680: 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 0a  ** the default..
3690: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53  */.#if defined(S
36a0: 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c  QLITE_SYSTEM_MAL
36b0: 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 53 51 4c  LOC)+defined(SQL
36c0: 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43  ITE_WIN32_MALLOC
36d0: 29 2b 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45  )+defined(SQLITE
36e0: 5f 4d 45 4d 44 45 42 55 47 29 3e 31 0a 23 20 65  _MEMDEBUG)>1.# e
36f0: 72 72 6f 72 20 22 41 74 20 6d 6f 73 74 20 6f 6e  rror "At most on
3700: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
3710: 6e 67 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ng compile-time 
3720: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
3730: 74 69 6f 6e 73 5c 0a 20 69 73 20 61 6c 6c 6f 77  tions\. is allow
3740: 73 3a 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d  s: SQLITE_SYSTEM
3750: 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 45 5f  _MALLOC, SQLITE_
3760: 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51  WIN32_MALLOC, SQ
3770: 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 22 0a 23  LITE_MEMDEBUG".#
3780: 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69 6e 65  endif.#if define
3790: 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f  d(SQLITE_SYSTEM_
37a0: 4d 41 4c 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28  MALLOC)+defined(
37b0: 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
37c0: 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 53 51 4c  LOC)+defined(SQL
37d0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d 3d 30  ITE_MEMDEBUG)==0
37e0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
37f0: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 31  _SYSTEM_MALLOC 1
3800: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49  .#endif../*.** I
3810: 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f  f SQLITE_MALLOC_
3820: 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20 6e 6f  SOFT_LIMIT is no
3830: 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 79  t zero, then try
3840: 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a 2a 20   to keep the.** 
3850: 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  sizes of memory 
3860: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65 6c 6f  allocations belo
3870: 77 20 74 68 69 73 20 76 61 6c 75 65 20 77 68 65  w this value whe
3880: 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2f 0a  re possible..*/.
3890: 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c  #if !defined(SQL
38a0: 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f  ITE_MALLOC_SOFT_
38b0: 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e 65 20  LIMIT).# define 
38c0: 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f  SQLITE_MALLOC_SO
38d0: 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a 23 65  FT_LIMIT 1024.#e
38e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65 20 6e  ndif../*.** We n
38f0: 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20 5f 58  eed to define _X
3900: 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73 20 66  OPEN_SOURCE as f
3910: 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65 72 20  ollows in order 
3920: 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72 65 63  to enable.** rec
3930: 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 20 6f  ursive mutexes o
3940: 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79 73 74  n most Unix syst
3950: 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20 4f 53  ems.  But Mac OS
3960: 20 58 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e   X is different.
3970: 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e 5f 53  .** The _XOPEN_S
3980: 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63 61 75  OURCE define cau
3990: 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f 72  ses problems for
39a0: 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61 72 65   Mac OS X we are
39b0: 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69 74 20   told,.** so it 
39c0: 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 72 65  is omitted there
39d0: 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
39e0: 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74 65 72  673..**.** Later
39f0: 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74 20 5f   we learn that _
3a00: 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69 73 20  XOPEN_SOURCE is 
3a10: 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f 72 72  poorly or incorr
3a20: 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ectly.** impleme
3a30: 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73 79 73  nted on some sys
3a40: 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61 76 6f  tems.  So we avo
3a50: 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74 20 61  id defining it a
3a60: 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74 20 69  t all.** if it i
3a70: 73 20 61 6c 72 65 61 64 79 20 64 65 66 69 6e 65  s already define
3a80: 64 20 6f 72 20 69 66 20 69 74 20 69 73 20 75 6e  d or if it is un
3a90: 6e 65 65 64 65 64 20 62 65 63 61 75 73 65 20 77  needed because w
3aa0: 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64 6f 69  e are.** not doi
3ab0: 6e 67 20 61 20 74 68 72 65 61 64 73 61 66 65 20  ng a threadsafe 
3ac0: 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74 20 23  build.  Ticket #
3ad0: 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2681..**.** See 
3ae0: 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32 37 34  also ticket #274
3af0: 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e  1..*/.#if !defin
3b00: 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45  ed(_XOPEN_SOURCE
3b10: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 5f  ) && !defined(__
3b20: 44 41 52 57 49 4e 5f 5f 29 20 26 26 20 21 64 65  DARWIN__) && !de
3b30: 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45 5f 5f 29  fined(__APPLE__)
3b40: 20 26 26 20 53 51 4c 49 54 45 5f 54 48 52 45 41   && SQLITE_THREA
3b50: 44 53 41 46 45 0a 23 20 20 64 65 66 69 6e 65 20  DSAFE.#  define 
3b60: 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 35 30  _XOPEN_SOURCE 50
3b70: 30 20 20 2f 2a 20 4e 65 65 64 65 64 20 74 6f 20  0  /* Needed to 
3b80: 65 6e 61 62 6c 65 20 70 74 68 72 65 61 64 20 72  enable pthread r
3b90: 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73  ecursive mutexes
3ba0: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a   */.#endif../*.*
3bb0: 2a 20 54 68 65 20 54 43 4c 20 68 65 61 64 65 72  * The TCL header
3bc0: 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65 65 64 65  s are only neede
3bd0: 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67  d when compiling
3be0: 20 74 68 65 20 54 43 4c 20 62 69 6e 64 69 6e 67   the TCL binding
3bf0: 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  s..*/.#if define
3c00: 64 28 53 51 4c 49 54 45 5f 54 43 4c 29 20 7c 7c  d(SQLITE_TCL) ||
3c10: 20 64 65 66 69 6e 65 64 28 54 43 4c 53 48 29 0a   defined(TCLSH).
3c20: 23 20 69 6e 63 6c 75 64 65 20 3c 74 63 6c 2e 68  # include <tcl.h
3c30: 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  >.#endif../*.** 
3c40: 4d 61 6e 79 20 70 65 6f 70 6c 65 20 61 72 65 20  Many people are 
3c50: 66 61 69 6c 69 6e 67 20 74 6f 20 73 65 74 20 2d  failing to set -
3c60: 44 4e 44 45 42 55 47 3d 31 20 77 68 65 6e 20 63  DNDEBUG=1 when c
3c70: 6f 6d 70 69 6c 69 6e 67 20 53 51 4c 69 74 65 2e  ompiling SQLite.
3c80: 0a 2a 2a 20 53 65 74 74 69 6e 67 20 4e 44 45 42  .** Setting NDEB
3c90: 55 47 20 6d 61 6b 65 73 20 74 68 65 20 63 6f 64  UG makes the cod
3ca0: 65 20 73 6d 61 6c 6c 65 72 20 61 6e 64 20 72 75  e smaller and ru
3cb0: 6e 20 66 61 73 74 65 72 2e 20 20 53 6f 20 74 68  n faster.  So th
3cc0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 6c  e following.** l
3cd0: 69 6e 65 73 20 61 72 65 20 61 64 64 65 64 20 74  ines are added t
3ce0: 6f 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  o automatically 
3cf0: 73 65 74 20 4e 44 45 42 55 47 20 75 6e 6c 65 73  set NDEBUG unles
3d00: 73 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 44  s the -DSQLITE_D
3d10: 45 42 55 47 3d 31 0a 2a 2a 20 6f 70 74 69 6f 6e  EBUG=1.** option
3d20: 20 69 73 20 73 65 74 2e 20 20 54 68 75 73 20 4e   is set.  Thus N
3d30: 44 45 42 55 47 20 62 65 63 6f 6d 65 73 20 61 6e  DEBUG becomes an
3d40: 20 6f 70 74 2d 69 6e 20 72 61 74 68 65 72 20 74   opt-in rather t
3d50: 68 61 6e 20 61 6e 20 6f 70 74 2d 6f 75 74 0a 2a  han an opt-out.*
3d60: 2a 20 66 65 61 74 75 72 65 2e 0a 2a 2f 0a 23 69  * feature..*/.#i
3d70: 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42 55  f !defined(NDEBU
3d80: 47 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 53  G) && !defined(S
3d90: 51 4c 49 54 45 5f 44 45 42 55 47 29 20 0a 23 20  QLITE_DEBUG) .# 
3da0: 64 65 66 69 6e 65 20 4e 44 45 42 55 47 20 31 0a  define NDEBUG 1.
3db0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
3dc0: 65 20 74 65 73 74 63 61 73 65 28 29 20 6d 61 63  e testcase() mac
3dd0: 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20 61 69  ro is used to ai
3de0: 64 20 69 6e 20 63 6f 76 65 72 61 67 65 20 74 65  d in coverage te
3df0: 73 74 69 6e 67 2e 20 20 57 68 65 6e 20 0a 2a 2a  sting.  When .**
3e00: 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 20   doing coverage 
3e10: 74 65 73 74 69 6e 67 2c 20 74 68 65 20 63 6f 6e  testing, the con
3e20: 64 69 74 69 6f 6e 20 69 6e 73 69 64 65 20 74 68  dition inside th
3e30: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
3e40: 20 74 65 73 74 63 61 73 65 28 29 20 6d 75 73 74   testcase() must
3e50: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 62 6f   be evaluated bo
3e60: 74 68 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73  th true and fals
3e70: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  e in order to.**
3e80: 20 67 65 74 20 66 75 6c 6c 20 62 72 61 6e 63 68   get full branch
3e90: 20 63 6f 76 65 72 61 67 65 2e 20 20 54 68 65 20   coverage.  The 
3ea0: 74 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 6f  testcase() macro
3eb0: 20 69 73 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20   is inserted.** 
3ec0: 74 6f 20 68 65 6c 70 20 65 6e 73 75 72 65 20 61  to help ensure a
3ed0: 64 65 71 75 61 74 65 20 74 65 73 74 20 63 6f 76  dequate test cov
3ee0: 65 72 61 67 65 20 69 6e 20 70 6c 61 63 65 73 20  erage in places 
3ef0: 77 68 65 72 65 20 73 69 6d 70 6c 65 0a 2a 2a 20  where simple.** 
3f00: 63 6f 6e 64 69 74 69 6f 6e 2f 64 65 63 69 73 69  condition/decisi
3f10: 6f 6e 20 63 6f 76 65 72 61 67 65 20 69 73 20 69  on coverage is i
3f20: 6e 61 64 65 71 75 61 74 65 2e 20 20 46 6f 72 20  nadequate.  For 
3f30: 65 78 61 6d 70 6c 65 2c 20 74 65 73 74 63 61 73  example, testcas
3f40: 65 28 29 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  e().** can be us
3f50: 65 64 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  ed to make sure 
3f60: 62 6f 75 6e 64 61 72 79 20 76 61 6c 75 65 73 20  boundary values 
3f70: 61 72 65 20 74 65 73 74 65 64 2e 20 20 46 6f 72  are tested.  For
3f80: 0a 2a 2a 20 62 69 74 6d 61 73 6b 20 74 65 73 74  .** bitmask test
3f90: 73 2c 20 74 65 73 74 63 61 73 65 28 29 20 63 61  s, testcase() ca
3fa0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6d 61 6b  n be used to mak
3fb0: 65 20 73 75 72 65 20 65 61 63 68 20 62 69 74 0a  e sure each bit.
3fc0: 2a 2a 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e  ** is significan
3fd0: 74 20 61 6e 64 20 75 73 65 64 20 61 74 20 6c 65  t and used at le
3fe0: 61 73 74 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 77  ast once.  On sw
3ff0: 69 74 63 68 20 73 74 61 74 65 6d 65 6e 74 73 0a  itch statements.
4000: 2a 2a 20 77 68 65 72 65 20 6d 75 6c 74 69 70 6c  ** where multipl
4010: 65 20 63 61 73 65 73 20 67 6f 20 74 6f 20 74 68  e cases go to th
4020: 65 20 73 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20  e same block of 
4030: 63 6f 64 65 2c 20 74 65 73 74 63 61 73 65 28 29  code, testcase()
4040: 0a 2a 2a 20 63 61 6e 20 69 6e 73 75 72 65 20 74  .** can insure t
4050: 68 61 74 20 61 6c 6c 20 63 61 73 65 73 20 61 72  hat all cases ar
4060: 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a  e evaluated..**.
4070: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
4080: 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 0a 53  _COVERAGE_TEST.S
4090: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 20 20  QLITE_PRIVATE   
40a0: 76 6f 69 64 20 73 71 6c 69 74 65 33 43 6f 76 65  void sqlite3Cove
40b0: 72 61 67 65 28 69 6e 74 29 3b 0a 23 20 64 65 66  rage(int);.# def
40c0: 69 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 20  ine testcase(X) 
40d0: 20 69 66 28 20 58 20 29 7b 20 73 71 6c 69 74 65   if( X ){ sqlite
40e0: 33 43 6f 76 65 72 61 67 65 28 5f 5f 4c 49 4e 45  3Coverage(__LINE
40f0: 5f 5f 29 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 64  __); }.#else.# d
4100: 65 66 69 6e 65 20 74 65 73 74 63 61 73 65 28 58  efine testcase(X
4110: 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ).#endif../*.** 
4120: 54 68 65 20 54 45 53 54 4f 4e 4c 59 20 6d 61 63  The TESTONLY mac
4130: 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  ro is used to en
4140: 63 6c 6f 73 65 20 76 61 72 69 61 62 6c 65 20 64  close variable d
4150: 65 63 6c 61 72 61 74 69 6f 6e 73 20 6f 72 0a 2a  eclarations or.*
4160: 2a 20 6f 74 68 65 72 20 62 69 74 73 20 6f 66 20  * other bits of 
4170: 63 6f 64 65 20 74 68 61 74 20 61 72 65 20 6e 65  code that are ne
4180: 65 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  eded to support 
4190: 74 68 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  the arguments.**
41a0: 20 77 69 74 68 69 6e 20 74 65 73 74 63 61 73 65   within testcase
41b0: 28 29 20 61 6e 64 20 61 73 73 65 72 74 28 29 20  () and assert() 
41c0: 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 21  macros..*/.#if !
41d0: 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29 20  defined(NDEBUG) 
41e0: 7c 7c 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54  || defined(SQLIT
41f0: 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 29  E_COVERAGE_TEST)
4200: 0a 23 20 64 65 66 69 6e 65 20 54 45 53 54 4f 4e  .# define TESTON
4210: 4c 59 28 58 29 20 20 58 0a 23 65 6c 73 65 0a 23  LY(X)  X.#else.#
4220: 20 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59   define TESTONLY
4230: 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  (X).#endif../*.*
4240: 2a 20 53 6f 6d 65 74 69 6d 65 73 20 77 65 20 6e  * Sometimes we n
4250: 65 65 64 20 61 20 73 6d 61 6c 6c 20 61 6d 6f 75  eed a small amou
4260: 6e 74 20 6f 66 20 63 6f 64 65 20 73 75 63 68 20  nt of code such 
4270: 61 73 20 61 20 76 61 72 69 61 62 6c 65 20 69 6e  as a variable in
4280: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a 20  itialization.** 
4290: 74 6f 20 73 65 74 75 70 20 66 6f 72 20 61 20 6c  to setup for a l
42a0: 61 74 65 72 20 61 73 73 65 72 74 28 29 20 73 74  ater assert() st
42b0: 61 74 65 6d 65 6e 74 2e 20 20 57 65 20 64 6f 20  atement.  We do 
42c0: 6e 6f 74 20 77 61 6e 74 20 74 68 69 73 20 63 6f  not want this co
42d0: 64 65 20 74 6f 0a 2a 2a 20 61 70 70 65 61 72 20  de to.** appear 
42e0: 77 68 65 6e 20 61 73 73 65 72 74 28 29 20 69 73  when assert() is
42f0: 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20   disabled.  The 
4300: 66 6f 6c 6c 6f 77 69 6e 67 20 6d 61 63 72 6f 20  following macro 
4310: 69 73 20 74 68 65 72 65 66 6f 72 65 0a 2a 2a 20  is therefore.** 
4320: 75 73 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  used to contain 
4330: 74 68 61 74 20 73 65 74 75 70 20 63 6f 64 65 2e  that setup code.
4340: 20 20 54 68 65 20 22 56 56 41 22 20 61 63 72 6f    The "VVA" acro
4350: 6e 79 6d 20 73 74 61 6e 64 73 20 66 6f 72 0a 2a  nym stands for.*
4360: 2a 20 22 56 65 72 69 66 69 63 61 74 69 6f 6e 2c  * "Verification,
4370: 20 56 61 6c 69 64 61 74 69 6f 6e 2c 20 61 6e 64   Validation, and
4380: 20 41 63 63 72 65 64 69 74 61 74 69 6f 6e 22 2e   Accreditation".
4390: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
43a0: 2c 20 74 68 65 0a 2a 2a 20 63 6f 64 65 20 77 69  , the.** code wi
43b0: 74 68 69 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 20  thin VVA_ONLY() 
43c0: 77 69 6c 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 75  will only run du
43d0: 72 69 6e 67 20 76 65 72 69 66 69 63 61 74 69 6f  ring verificatio
43e0: 6e 20 70 72 6f 63 65 73 73 65 73 2e 0a 2a 2f 0a  n processes..*/.
43f0: 23 69 66 6e 64 65 66 20 4e 44 45 42 55 47 0a 23  #ifndef NDEBUG.#
4400: 20 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59   define VVA_ONLY
4410: 28 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 64  (X)  X.#else.# d
4420: 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58  efine VVA_ONLY(X
4430: 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ).#endif../*.** 
4440: 54 68 65 20 41 4c 57 41 59 53 20 61 6e 64 20 4e  The ALWAYS and N
4450: 45 56 45 52 20 6d 61 63 72 6f 73 20 73 75 72 72  EVER macros surr
4460: 6f 75 6e 64 20 62 6f 6f 6c 65 61 6e 20 65 78 70  ound boolean exp
4470: 72 65 73 73 69 6f 6e 73 20 77 68 69 63 68 20 0a  ressions which .
4480: 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ** are intended 
4490: 74 6f 20 61 6c 77 61 79 73 20 62 65 20 74 72 75  to always be tru
44a0: 65 20 6f 72 20 66 61 6c 73 65 2c 20 72 65 73 70  e or false, resp
44b0: 65 63 74 69 76 65 6c 79 2e 20 20 53 75 63 68 0a  ectively.  Such.
44c0: 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63  ** expressions c
44d0: 6f 75 6c 64 20 62 65 20 6f 6d 69 74 74 65 64 20  ould be omitted 
44e0: 66 72 6f 6d 20 74 68 65 20 63 6f 64 65 20 63 6f  from the code co
44f0: 6d 70 6c 65 74 65 6c 79 2e 20 20 42 75 74 20 74  mpletely.  But t
4500: 68 65 79 0a 2a 2a 20 61 72 65 20 69 6e 63 6c 75  hey.** are inclu
4510: 64 65 64 20 69 6e 20 61 20 66 65 77 20 63 61 73  ded in a few cas
4520: 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  es in order to e
4530: 6e 68 61 6e 63 65 20 74 68 65 20 72 65 73 69 6c  nhance the resil
4540: 69 65 6e 63 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  ience.** of SQLi
4550: 74 65 20 74 6f 20 75 6e 65 78 70 65 63 74 65 64  te to unexpected
4560: 20 62 65 68 61 76 69 6f 72 20 2d 20 74 6f 20 6d   behavior - to m
4570: 61 6b 65 20 74 68 65 20 63 6f 64 65 20 22 73 65  ake the code "se
4580: 6c 66 2d 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 6f  lf-healing".** o
4590: 72 20 22 64 75 63 74 69 6c 65 22 20 72 61 74 68  r "ductile" rath
45a0: 65 72 20 74 68 61 6e 20 62 65 69 6e 67 20 22 62  er than being "b
45b0: 72 69 74 74 6c 65 22 20 61 6e 64 20 63 72 61 73  rittle" and cras
45c0: 68 69 6e 67 20 61 74 20 74 68 65 20 66 69 72 73  hing at the firs
45d0: 74 0a 2a 2a 20 68 69 6e 74 20 6f 66 20 75 6e 70  t.** hint of unp
45e0: 6c 61 6e 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  lanned behavior.
45f0: 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
4600: 77 6f 72 64 73 2c 20 41 4c 57 41 59 53 20 61 6e  words, ALWAYS an
4610: 64 20 4e 45 56 45 52 20 61 72 65 20 61 64 64 65  d NEVER are adde
4620: 64 20 66 6f 72 20 64 65 66 65 6e 73 69 76 65 20  d for defensive 
4630: 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  code..**.** When
4640: 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 20   doing coverage 
4650: 74 65 73 74 69 6e 67 20 41 4c 57 41 59 53 20 61  testing ALWAYS a
4660: 6e 64 20 4e 45 56 45 52 20 61 72 65 20 68 61 72  nd NEVER are har
4670: 64 2d 63 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 65  d-coded to.** be
4680: 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 20   true and false 
4690: 73 6f 20 74 68 61 74 20 74 68 65 20 75 6e 72 65  so that the unre
46a0: 61 63 68 61 62 6c 65 20 63 6f 64 65 20 74 68 65  achable code the
46b0: 6e 20 73 70 65 63 69 66 79 20 77 69 6c 6c 0a 2a  n specify will.*
46c0: 2a 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64  * not be counted
46d0: 20 61 73 20 75 6e 74 65 73 74 65 64 20 63 6f 64   as untested cod
46e0: 65 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  e..*/.#if define
46f0: 64 28 53 51 4c 49 54 45 5f 43 4f 56 45 52 41 47  d(SQLITE_COVERAG
4700: 45 5f 54 45 53 54 29 0a 23 20 64 65 66 69 6e 65  E_TEST).# define
4710: 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20   ALWAYS(X)      
4720: 28 31 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56  (1).# define NEV
4730: 45 52 28 58 29 20 20 20 20 20 20 20 28 30 29 0a  ER(X)       (0).
4740: 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 4e  #elif !defined(N
4750: 44 45 42 55 47 29 0a 23 20 64 65 66 69 6e 65 20  DEBUG).# define 
4760: 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28  ALWAYS(X)      (
4770: 28 58 29 3f 31 3a 28 61 73 73 65 72 74 28 30 29  (X)?1:(assert(0)
4780: 2c 30 29 29 0a 23 20 64 65 66 69 6e 65 20 4e 45  ,0)).# define NE
4790: 56 45 52 28 58 29 20 20 20 20 20 20 20 28 28 58  VER(X)       ((X
47a0: 29 3f 28 61 73 73 65 72 74 28 30 29 2c 31 29 3a  )?(assert(0),1):
47b0: 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  0).#else.# defin
47c0: 65 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20  e ALWAYS(X)     
47d0: 20 28 58 29 0a 23 20 64 65 66 69 6e 65 20 4e 45   (X).# define NE
47e0: 56 45 52 28 58 29 20 20 20 20 20 20 20 28 58 29  VER(X)       (X)
47f0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 52  .#endif../*.** R
4800: 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d  eturn true (non-
4810: 7a 65 72 6f 29 20 69 66 20 74 68 65 20 69 6e 70  zero) if the inp
4820: 75 74 20 69 73 20 61 20 69 6e 74 65 67 65 72 20  ut is a integer 
4830: 74 68 61 74 20 69 73 20 74 6f 6f 20 6c 61 72 67  that is too larg
4840: 65 0a 2a 2a 20 74 6f 20 66 69 74 20 69 6e 20 33  e.** to fit in 3
4850: 32 2d 62 69 74 73 2e 20 20 54 68 69 73 20 6d 61  2-bits.  This ma
4860: 63 72 6f 20 69 73 20 75 73 65 64 20 69 6e 73 69  cro is used insi
4870: 64 65 20 6f 66 20 76 61 72 69 6f 75 73 20 74 65  de of various te
4880: 73 74 63 61 73 65 28 29 0a 2a 2a 20 6d 61 63 72  stcase().** macr
4890: 6f 73 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  os to verify tha
48a0: 74 20 77 65 20 68 61 76 65 20 74 65 73 74 65 64  t we have tested
48b0: 20 53 51 4c 69 74 65 20 66 6f 72 20 6c 61 72 67   SQLite for larg
48c0: 65 2d 66 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a  e-file support..
48d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 49 53 5f 42 49  */.#define IS_BI
48e0: 47 5f 49 4e 54 28 58 29 20 20 28 28 28 58 29 26  G_INT(X)  (((X)&
48f0: 7e 28 69 36 34 29 30 78 66 66 66 66 66 66 66 66  ~(i64)0xffffffff
4900: 29 21 3d 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  )!=0)../*.** The
4910: 20 6d 61 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 28   macro unlikely(
4920: 29 20 69 73 20 61 20 68 69 6e 74 20 74 68 61 74  ) is a hint that
4930: 20 73 75 72 72 6f 75 6e 64 73 20 61 20 62 6f 6f   surrounds a boo
4940: 6c 65 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  lean.** expressi
4950: 6f 6e 20 74 68 61 74 20 69 73 20 75 73 75 61 6c  on that is usual
4960: 6c 79 20 66 61 6c 73 65 2e 20 20 4d 61 63 72 6f  ly false.  Macro
4970: 20 6c 69 6b 65 6c 79 28 29 20 73 75 72 72 6f 75   likely() surrou
4980: 6e 64 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e  nds.** a boolean
4990: 20 65 78 70 72 65 73 73 69 6f 6e 20 74 68 61 74   expression that
49a0: 20 69 73 20 75 73 75 61 6c 6c 79 20 74 72 75 65   is usually true
49b0: 2e 20 20 47 43 43 20 69 73 20 61 62 6c 65 20 74  .  GCC is able t
49c0: 6f 0a 2a 2a 20 75 73 65 20 74 68 65 73 65 20 68  o.** use these h
49d0: 69 6e 74 73 20 74 6f 20 67 65 6e 65 72 61 74 65  ints to generate
49e0: 20 62 65 74 74 65 72 20 63 6f 64 65 2c 20 73 6f   better code, so
49f0: 6d 65 74 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 20  metimes..*/.#if 
4a00: 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f  defined(__GNUC__
4a10: 29 20 26 26 20 30 0a 23 20 64 65 66 69 6e 65 20  ) && 0.# define 
4a20: 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 5f 5f 62  likely(X)    __b
4a30: 75 69 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 58  uiltin_expect((X
4a40: 29 2c 31 29 0a 23 20 64 65 66 69 6e 65 20 75 6e  ),1).# define un
4a50: 6c 69 6b 65 6c 79 28 58 29 20 20 5f 5f 62 75 69  likely(X)  __bui
4a60: 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 2c  ltin_expect((X),
4a70: 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  0).#else.# defin
4a80: 65 20 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 21  e likely(X)    !
4a90: 21 28 58 29 0a 23 20 64 65 66 69 6e 65 20 75 6e  !(X).# define un
4aa0: 6c 69 6b 65 6c 79 28 58 29 20 20 21 21 28 58 29  likely(X)  !!(X)
4ab0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a  .#endif../******
4ac0: 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65  ******** Include
4ad0: 20 73 71 6c 69 74 65 33 2e 68 20 69 6e 20 74 68   sqlite3.h in th
4ae0: 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69  e middle of sqli
4af0: 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a  teInt.h ********
4b00: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  *******/./******
4b10: 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66  ******** Begin f
4b20: 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a  ile sqlite3.h **
4b30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b50: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32  *******/./*.** 2
4b60: 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35  001 September 15
4b70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
4b80: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
4b90: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
4ba0: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
4bb0: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
4bc0: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
4bd0: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
4be0: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
4bf0: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
4c00: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
4c10: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
4c20: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
4c30: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
4c40: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
4c50: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
4c60: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
4c70: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
4c80: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
4c90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ca0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4cb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4cc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
4cd0: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
4ce0: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
4cf0: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
4d00: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
4d10: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
4d20: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
4d30: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
4d40: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
4d50: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
4d60: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
4d70: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
4d80: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
4d90: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
4da0: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
4db0: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
4dc0: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
4dd0: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
4de0: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
4df0: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
4e00: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
4e10: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
4e20: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
4e30: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
4e40: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
4e50: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
4e60: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
4e70: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
4e80: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
4e90: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
4ea0: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
4eb0: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
4ec0: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
4ed0: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
4ee0: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
4ef0: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
4f00: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
4f10: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
4f20: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
4f30: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
4f40: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
4f50: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
4f60: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
4f70: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
4f80: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
4f90: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
4fa0: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
4fb0: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
4fc0: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
4fd0: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
4fe0: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
4ff0: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
5000: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
5010: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
5020: 72 65 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70  re suppose to op
5030: 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  erate..**.** The
5040: 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69   name of this fi
5050: 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75  le under configu
5060: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
5070: 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69  t is "sqlite.h.i
5080: 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66  n"..** The makef
5090: 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d  ile makes some m
50a0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20  inor changes to 
50b0: 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 20  this file (such 
50c0: 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20  as inserting.** 
50d0: 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  the version numb
50e0: 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20  er) and changes 
50f0: 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c  its name to "sql
5100: 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61  ite3.h" as.** pa
5110: 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20  rt of the build 
5120: 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e  process..*/.#ifn
5130: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  def _SQLITE3_H_.
5140: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33  #define _SQLITE3
5150: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74  _H_.#include <st
5160: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e  darg.h>     /* N
5170: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65  eeded for the de
5180: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c  finition of va_l
5190: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61  ist */../*.** Ma
51a0: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63  ke sure we can c
51b0: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66  all this stuff f
51c0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20  rom C++..*/.#if 
51d0: 30 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23  0.extern "C" {.#
51e0: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64  endif.../*.** Ad
51f0: 64 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  d the ability to
5200: 20 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72   override 'exter
5210: 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  n'.*/.#ifndef SQ
5220: 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65  LITE_EXTERN.# de
5230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45  fine SQLITE_EXTE
5240: 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66  RN extern.#endif
5250: 0a 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  ..#ifndef SQLITE
5260: 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51  _API.# define SQ
5270: 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a  LITE_API.#endif.
5280: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f  ../*.** These no
5290: 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75  -op macros are u
52a0: 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20  sed in front of 
52b0: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61  interfaces to ma
52c0: 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65  rk those.** inte
52d0: 72 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72  rfaces as either
52e0: 20 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65   deprecated or e
52f0: 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65  xperimental.  Ne
5300: 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  w applications.*
5310: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65  * should not use
5320: 20 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65   deprecated inte
5330: 72 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72  rfaces - they ar
5340: 65 20 73 75 70 70 6f 72 74 20 66 6f 72 20 62 61  e support for ba
5350: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
5360: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20  tibility only.  
5370: 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74  Application writ
5380: 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77  ers should be aw
5390: 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65  are that.** expe
53a0: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
53b0: 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 20  ces are subject 
53c0: 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69  to change in poi
53d0: 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  nt releases..**.
53e0: 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20  ** These macros 
53f0: 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20  used to resolve 
5400: 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73  to various kinds
5410: 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67   of compiler mag
5420: 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64  ic that.** would
5430: 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e   generate warnin
5440: 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20  g messages when 
5450: 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e 20  they were used. 
5460: 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d   But that.** com
5470: 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65  piler magic ende
5480: 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20  d up generating 
5490: 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66  such a flurry of
54a0: 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20   bug reports.** 
54b0: 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61 6b  that we have tak
54c0: 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e  en it all out an
54d0: 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75  d gone back to u
54e0: 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e  sing simple.** n
54f0: 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23  oop macros..*/.#
5500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
5510: 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65  PRECATED.#define
5520: 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45   SQLITE_EXPERIME
5530: 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75  NTAL../*.** Ensu
5540: 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73  re these symbols
5550: 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65   were not define
5560: 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f  d by some previo
5570: 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a  us header file..
5580: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
5590: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
55a0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
55b0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
55c0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
55d0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
55e0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
55f0: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
5600: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
5610: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
5620: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a  ersion Numbers.*
5630: 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49  *.** ^(The [SQLI
5640: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 72  TE_VERSION] C pr
5650: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
5660: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e   in the sqlite3.
5670: 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c  h header.** eval
5680: 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 6e  uates to a strin
5690: 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69  g literal that i
56a0: 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72  s the SQLite ver
56b0: 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66  sion in the.** f
56c0: 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 68  ormat "X.Y.Z" wh
56d0: 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 6a  ere X is the maj
56e0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
56f0: 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 0a  r (always 3 for.
5700: 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 20  ** SQLite3) and 
5710: 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  Y is the minor v
5720: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
5730: 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 61  d Z is the relea
5740: 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20  se number.)^.** 
5750: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
5760: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20  RSION_NUMBER] C 
5770: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
5780: 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61  ro resolves to a
5790: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74  n integer.** wit
57a0: 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31  h the value (X*1
57b0: 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20  000000 + Y*1000 
57c0: 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c  + Z) where X, Y,
57d0: 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 73   and Z are the s
57e0: 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75  ame.** numbers u
57f0: 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56  sed in [SQLITE_V
5800: 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68  ERSION].)^.** Th
5810: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
5820: 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 20  _NUMBER for any 
5830: 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f 66  given release of
5840: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
5850: 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 74  o.** be larger t
5860: 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 20  han the release 
5870: 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 73  from which it is
5880: 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 65   derived.  Eithe
5890: 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68  r Y will.** be h
58a0: 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64  eld constant and
58b0: 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65   Z will be incre
58c0: 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 59  mented or else Y
58d0: 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65   will be increme
58e0: 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69  nted.** and Z wi
58f0: 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 7a  ll be reset to z
5900: 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65  ero..**.** Since
5910: 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c   version 3.6.18,
5920: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
5930: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
5940: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
5950: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
5960: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
5970: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
5980: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
5990: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
59a0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
59b0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
59c0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
59d0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
59e0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
59f0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
5a00: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
5a10: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
5a20: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
5a30: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
5a40: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
5a50: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
5a60: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
5a70: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
5a80: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e  -in (UTC) and an
5a90: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
5aa0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
5ab0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
5ac0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
5ad0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
5ae0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
5af0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
5b00: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
5b10: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
5b20: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
5b30: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
5b40: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
5b50: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
5b60: 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 37 2e 31  ON        "3.7.1
5b70: 31 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  1".#define SQLIT
5b80: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
5b90: 20 33 30 30 37 30 31 31 0a 23 64 65 66 69 6e 65   3007011.#define
5ba0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
5bb0: 44 20 20 20 20 20 20 22 32 30 31 32 2d 30 33 2d  D      "2012-03-
5bc0: 31 39 20 31 37 3a 34 32 3a 34 36 20 30 33 36 33  19 17:42:46 0363
5bd0: 39 35 63 30 61 38 65 30 38 38 38 33 62 31 31 64  95c0a8e08883b11d
5be0: 66 30 32 35 65 33 64 61 39 65 32 34 36 31 65 34  f025e3da9e2461e4
5bf0: 62 31 65 62 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b1eb"../*.** CAP
5c00: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
5c10: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
5c20: 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f  Numbers.** KEYWO
5c30: 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72  RDS: sqlite3_ver
5c40: 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f  sion, sqlite3_so
5c50: 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65  urceid.**.** The
5c60: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72  se interfaces pr
5c70: 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69  ovide the same i
5c80: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68  nformation as th
5c90: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  e [SQLITE_VERSIO
5ca0: 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56  N],.** [SQLITE_V
5cb0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20  ERSION_NUMBER], 
5cc0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  and [SQLITE_SOUR
5cd0: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
5ce0: 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20  essor macros.** 
5cf0: 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74  but are associat
5d00: 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72  ed with the libr
5d10: 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ary instead of t
5d20: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20  he header file. 
5d30: 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70   ^(Cautious.** p
5d40: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
5d50: 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28   include assert(
5d60: 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  ) statements in 
5d70: 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f  their applicatio
5d80: 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74  n to.** verify t
5d90: 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72  hat values retur
5da0: 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74  ned by these int
5db0: 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68  erfaces match th
5dc0: 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74  e macros in.** t
5dd0: 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74  he header, and t
5de0: 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20  hus insure that 
5df0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
5e00: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
5e10: 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62  ith matching lib
5e20: 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20  rary and header 
5e30: 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c  files..**.** <bl
5e40: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
5e50: 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65  * assert( sqlite
5e60: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
5e70: 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45  ber()==SQLITE_VE
5e80: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a  RSION_NUMBER );.
5e90: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
5ea0: 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  p(sqlite3_source
5eb0: 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52  id(),SQLITE_SOUR
5ec0: 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20  CE_ID)==0 );.** 
5ed0: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
5ee0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
5ef0: 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49  n(),SQLITE_VERSI
5f00: 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70  ON)==0 );.** </p
5f10: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
5f20: 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
5f30: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20  lite3_version[] 
5f40: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
5f50: 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78  contains the tex
5f60: 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52  t of [SQLITE_VER
5f70: 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20  SION].** macro. 
5f80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69   ^The sqlite3_li
5f90: 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74  bversion() funct
5fa0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ion returns a po
5fb0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
5fc0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  to the sqlite3_v
5fd0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
5fe0: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73  constant.  The s
5ff0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
6000: 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  n().** function 
6010: 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  is provided for 
6020: 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63  use in DLLs sinc
6030: 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61  e DLL users usua
6040: 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a  lly do not have.
6050: 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73  ** direct access
6060: 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74   to string const
6070: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20  ants within the 
6080: 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  DLL.  ^The.** sq
6090: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
60a0: 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69  _number() functi
60b0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  on returns an in
60c0: 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a  teger equal to.*
60d0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
60e0: 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65  N_NUMBER].  ^The
60f0: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
6100: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  d() function ret
6110: 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  urns .** a point
6120: 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63  er to a string c
6130: 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61  onstant whose va
6140: 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  lue is the same 
6150: 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  as the .** [SQLI
6160: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
6170: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
6180: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ro..**.** See al
6190: 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73  so: [sqlite_vers
61a0: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
61b0: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e  te_source_id()].
61c0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
61d0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
61e0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51  3_version[] = SQ
61f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51  LITE_VERSION;.SQ
6200: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
6210: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
6220: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
6230: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
6240: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
6250: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
6260: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
6270: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
6280: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
6290: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
62a0: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
62b0: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
62c0: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
62d0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
62e0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
62f0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
6300: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
6310: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
6320: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
6330: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
6340: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
6350: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
6360: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
6370: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
6380: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
6390: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
63a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
63b0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
63c0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
63d0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
63e0: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
63f0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
6400: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
6410: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
6420: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
6430: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
6440: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
6450: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
6460: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
6470: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
6480: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
6490: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
64a0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
64b0: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
64c0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
64d0: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
64e0: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
64f0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
6500: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
6510: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
6520: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
6530: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
6540: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
6550: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
6560: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
6570: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
6580: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6590: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
65a0: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
65b0: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
65c0: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
65d0: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
65e0: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
65f0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
6600: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
6610: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
6620: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
6630: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
6640: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
6650: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
6660: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
6670: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
6680: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
6690: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
66a0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
66b0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
66c0: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74  ption_used(const
66d0: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29   char *zOptName)
66e0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
66f0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
6700: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6710: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
6720: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
6730: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
6740: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
6750: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
6760: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
6770: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
6780: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
6790: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
67a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
67b0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
67c0: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74  exing code omitt
67d0: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a  ed due to the.**
67e0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
67f0: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AFE] compile-tim
6800: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73  e option being s
6810: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53  et to 0..**.** S
6820: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d  QLite can be com
6830: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69  piled with or wi
6840: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20  thout mutexes.  
6850: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  When.** the [SQL
6860: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
6870: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
6880: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20  acro is 1 or 2, 
6890: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
68a0: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74  nabled and SQLit
68b0: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e  e is threadsafe.
68c0: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53    When the.** [S
68d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
68e0: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a  ] macro is 0, .*
68f0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
6900: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
6910: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
6920: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
6930: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
6940: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72   concurrently fr
6950: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  om more than one
6960: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45   thread..**.** E
6970: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20  nabling mutexes 
6980: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61  incurs a measura
6990: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ble performance 
69a0: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69  penalty..** So i
69b0: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74  f speed is of ut
69c0: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c  most importance,
69d0: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20   it makes sense 
69e0: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  to disable.** th
69f0: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20  e mutexes.  But 
6a00: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65  for maximum safe
6a10: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ty, mutexes shou
6a20: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  ld be enabled..*
6a30: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
6a40: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
6a50: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
6a60: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
6a70: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
6a80: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70  e used by an app
6a90: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65  lication to make
6aa0: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a   sure that the.*
6ab0: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
6ac0: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c  ite that it is l
6ad0: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77  inking against w
6ae0: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
6af0: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20  .** the desired 
6b00: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b  setting of the [
6b10: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
6b20: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  E] macro..**.** 
6b30: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f  This interface o
6b40: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74  nly reports on t
6b50: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
6b60: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a  mutex setting.**
6b70: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
6b80: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67  THREADSAFE] flag
6b90: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
6ba0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
6bb0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
6bc0: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20  FE=1 or =2 then 
6bd0: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
6be0: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
6bf0: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
6c00: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
6c10: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
6c20: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
6c30: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
6c40: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
6c50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
6c60: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
6c70: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
6c80: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
6c90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
6ca0: 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74  TEX].  ^(The ret
6cb0: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
6cc0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65  .** sqlite3_thre
6cd0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
6ce0: 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65  n shows only the
6cf0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65   compile-time se
6d00: 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65  tting of.** thre
6d10: 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61  ad safety, not a
6d20: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e  ny run-time chan
6d30: 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74  ges to that sett
6d40: 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73  ing made by.** s
6d50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
6d60: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
6d70: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
6d80: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74  e from sqlite3_t
6d90: 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69  hreadsafe().** i
6da0: 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63  s unchanged by c
6db0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
6dc0: 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a  config().)^.**.*
6dd0: 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61  * See the [threa
6de0: 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d  ding mode] docum
6df0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
6e00: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
6e10: 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
6e20: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
6e30: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
6e40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6e50: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
6e60: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20  ction Handle.** 
6e70: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62  KEYWORDS: {datab
6e80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20  ase connection} 
6e90: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
6ea0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  tions}.**.** Eac
6eb0: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
6ec0: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
6ed0: 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74  ented by a point
6ee0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
6ef0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71  e of.** the opaq
6f00: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d  ue structure nam
6f10: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49  ed "sqlite3".  I
6f20: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74  t is useful to t
6f30: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74  hink of an sqlit
6f40: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73  e3.** pointer as
6f50: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65   an object.  The
6f60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
6f70: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
6f80: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  16()], and.** [s
6f90: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6fa0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ] interfaces are
6fb0: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
6fc0: 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  s, and [sqlite3_
6fd0: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69  close()].** is i
6fe0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20  ts destructor.  
6ff0: 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f  There are many o
7000: 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  ther interfaces 
7010: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
7020: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
7030: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
7040: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
7050: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
7060: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
7070: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
7080: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
7090: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
70a0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
70b0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
70c0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
70d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
70e0: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
70f0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
7100: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
7110: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
7120: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
7130: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
7140: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
7150: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
7160: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
7170: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
7180: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
7190: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
71a0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
71b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
71c0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
71d0: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
71e0: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
71f0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
7200: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
7210: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
7220: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
7230: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
7240: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
7250: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
7260: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
7270: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
7280: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
7290: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
72a0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
72b0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
72c0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
72d0: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
72e0: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
72f0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
7300: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
7310: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
7320: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
7330: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
7340: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
7350: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
7360: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
7370: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
7380: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
7390: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
73a0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
73b0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
73c0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
73d0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
73e0: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
73f0: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
7400: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
7410: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
7420: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
7430: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
7440: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
7450: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
7460: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
7470: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
7480: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
7490: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
74a0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
74b0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
74c0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
74d0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
74e0: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
74f0: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
7500: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
7510: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
7520: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
7530: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
7540: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
7550: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
7560: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
7570: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
7580: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
7590: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
75a0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
75b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
75c0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
75d0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
75e0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
75f0: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
7600: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72  qlite3_close() r
7610: 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64 65  outine is the de
7620: 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
7630: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
7640: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
7650: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
7660: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
7670: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   if the [sqlite3
7680: 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73  ] object is.** s
7690: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
76a0: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
76b0: 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75 72 63  sociated resourc
76c0: 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74  es are deallocat
76d0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ed..**.** Applic
76e0: 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c  ations must [sql
76f0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
7700: 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70  finalize] all [p
7710: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
7720: 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ts].** and [sqli
7730: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
7740: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
7750: 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63  B handles] assoc
7760: 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  iated with.** th
7770: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
7780: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
7790: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
77a0: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
77b0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
77c0: 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  e() is called on
77d0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
77e0: 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74  nection] that st
77f0: 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74  ill has.** outst
7800: 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64  anding [prepared
7810: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20   statements] or 
7820: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
7830: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 0a  then it returns.
7840: 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a  ** SQLITE_BUSY..
7850: 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74  **.** ^If [sqlit
7860: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69  e3_close()] is i
7870: 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74  nvoked while a t
7880: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
7890: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
78a0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
78b0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
78c0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
78d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
78e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
78f0: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
7900: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
7910: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
7920: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
7930: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
7940: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
7950: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
7960: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
7970: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
7980: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
7990: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
79a0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
79b0: 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68 20 61  3_close() with a
79c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72   NULL pointer ar
79d0: 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20  gument is a .** 
79e0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
79f0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
7a00: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  t sqlite3_close(
7a10: 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a  sqlite3 *);../*.
7a20: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
7a30: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
7a40: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
7a50: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
7a60: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
7a70: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
7a80: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
7a90: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
7aa0: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
7ab0: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
7ac0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
7ad0: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
7ae0: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
7af0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
7b00: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
7b10: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
7b20: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
7b30: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
7b40: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
7b50: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
7b60: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
7b70: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
7b80: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
7b90: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
7ba0: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
7bb0: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
7bc0: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
7bd0: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
7be0: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
7bf0: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
7c00: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
7c10: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
7c20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
7c30: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
7c40: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
7c50: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
7c60: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
7c70: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
7c80: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
7c90: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
7ca0: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
7cb0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
7cc0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
7cd0: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
7ce0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
7cf0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
7d00: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
7d10: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
7d20: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
7d30: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
7d40: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
7d50: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
7d60: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
7d70: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
7d80: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
7d90: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
7da0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
7db0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
7dc0: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
7dd0: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
7de0: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
7df0: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
7e00: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
7e10: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
7e20: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
7e30: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
7e40: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
7e50: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
7e60: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
7e70: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
7e80: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
7e90: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
7ea0: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
7eb0: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
7ec0: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
7ed0: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
7ee0: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
7ef0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
7f00: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
7f10: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
7f20: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
7f30: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
7f40: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
7f50: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
7f60: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
7f70: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
7f80: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
7f90: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
7fa0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
7fb0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
7fc0: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
7fd0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
7fe0: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
7ff0: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
8000: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
8010: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
8020: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
8030: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
8040: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
8050: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
8060: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
8070: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
8080: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
8090: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
80a0: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
80b0: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
80c0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
80d0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
80e0: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
80f0: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
8100: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
8110: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
8120: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
8130: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
8140: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
8150: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
8160: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
8170: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
8180: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
8190: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
81a0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
81b0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
81c0: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
81d0: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
81e0: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
81f0: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
8200: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
8210: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
8220: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
8230: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
8240: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
8250: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
8260: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
8270: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
8280: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
8290: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
82a0: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
82b0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
82c0: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
82d0: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
82e0: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
82f0: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
8300: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
8310: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
8320: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
8330: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
8340: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
8350: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
8360: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
8370: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
8380: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
8390: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
83a0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
83b0: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
83c0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
83d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
83e0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
83f0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
8400: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
8410: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
8420: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
8430: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
8440: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
8450: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
8460: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
8470: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
8480: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
8490: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
84a0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
84b0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
84c0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
84d0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
84e0: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
84f0: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
8500: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
8510: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
8520: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
8530: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
8540: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
8550: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
8560: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
8570: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
8580: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
8590: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
85a0: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
85b0: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
85c0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
85d0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
85e0: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
85f0: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
8600: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
8610: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
8620: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
8630: 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20 63  lose [database c
8640: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
8650: 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  fied by.**      
8660: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
8670: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
8680: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
8690: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
86a0: 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ing..** <li> The
86b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
86c0: 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  t not modify the
86d0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
86e0: 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  ext passed into.
86f0: 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20  **      the 2nd 
8700: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
8710: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
8720: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
8730: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
8740: 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ul>.*/.SQLITE_
8750: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
8760: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
8770: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
8780: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8790: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
87a0: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
87b0: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
87c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
87d0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
87e0: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
87f0: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
8800: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
8810: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
8820: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
8830: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
8840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8850: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8860: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
8870: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
8880: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
8890: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
88a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
88b0: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
88c0: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
88d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
88e0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
88f0: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
8900: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
8910: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
8920: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73  * KEYWORDS: {res
8930: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c  ult code} {resul
8940: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d  t codes}.**.** M
8950: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
8960: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
8970: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
8980: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
8990: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
89a0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
89b0: 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  te success or fa
89c0: 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  ilure..**.** New
89d0: 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79   error codes may
89e0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
89f0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
8a00: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  SQLite..**.** Se
8a10: 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
8a20: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
8a30: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
8a40: 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  es],.** [sqlite3
8a50: 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
8a60: 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c  t()] [SQLITE_ROL
8a70: 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63  LBACK | result c
8a80: 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  odes]..*/.#defin
8a90: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
8aa0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
8ab0: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
8ac0: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
8ad0: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
8ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8af0: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
8b00: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
8b10: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
8b20: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
8b30: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
8b40: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
8b50: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
8b60: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
8b70: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
8b80: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
8b90: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
8ba0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
8bb0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
8bc0: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
8bd0: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
8be0: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
8bf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8c00: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
8c10: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
8c20: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
8c30: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
8c40: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
8c50: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
8c60: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
8c70: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
8c80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
8c90: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
8ca0: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
8cb0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
8cc0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
8cd0: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
8ce0: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
8cf0: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
8d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8d10: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
8d20: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
8d30: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
8d40: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
8d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8d60: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
8d70: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
8d80: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
8d90: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
8da0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
8db0: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
8dc0: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
8dd0: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
8de0: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
8df0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
8e00: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
8e10: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
8e20: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8e30: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
8e40: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
8e50: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
8e60: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
8e70: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
8e80: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
8e90: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
8ea0: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
8eb0: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
8ec0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
8ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
8ee0: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
8ef0: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
8f00: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
8f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
8f20: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
8f30: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
8f40: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
8f50: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
8f60: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
8f70: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
8f80: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
8f90: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
8fa0: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
8fb0: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
8fc0: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
8fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
8ff0: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
9000: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
9010: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
9020: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
9030: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
9040: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
9050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9060: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
9070: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
9080: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
9090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
90a0: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
90b0: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
90c0: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
90d0: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
90e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
90f0: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
9100: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
9110: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
9120: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
9130: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
9140: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
9150: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
9160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
9170: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
9180: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
9190: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
91a0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
91b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
91c0: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
91d0: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
91e0: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
91f0: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
9200: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
9210: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
9220: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
9230: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
9240: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
9250: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
9260: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
9270: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
9280: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
9290: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
92a0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
92b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
92c0: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
92d0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
92e0: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72  S: {extended err
92f0: 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64  or code} {extend
9300: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  ed error codes}.
9310: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
9320: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
9330: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65  de} {extended re
9340: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
9350: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74  * In its default
9360: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
9370: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
9380: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
9390: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20  f 26 integer.** 
93a0: 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73  [SQLITE_OK | res
93b0: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
93c0: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
93d0: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
93e0: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
93f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
9400: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
9410: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
9420: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
9430: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
9440: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
9450: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
9460: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
9470: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
9480: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
9490: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
94a0: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
94b0: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
94c0: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
94d0: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
94e0: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
94f0: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
9500: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
9510: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
9520: 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65  errors. The exte
9530: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
9540: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72  s are enabled or
9550: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20   disabled.** on 
9560: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63  a per database c
9570: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20  onnection basis 
9580: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
9590: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
95a0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41  esult_codes()] A
95b0: 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f  PI..**.** Some o
95c0: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
95d0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
95e0: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64  codes are listed
95f0: 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61   here..** One ma
9600: 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d  y expect the num
9610: 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20  ber of extended 
9620: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c  result codes wil
9630: 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f  l be expand.** o
9640: 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77  ver time.  Softw
9650: 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78  are that uses ex
9660: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
9670: 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63  des should expec
9680: 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20  t.** to see new 
9690: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20  result codes in 
96a0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
96b0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
96c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72   The SQLITE_OK r
96d0: 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20  esult code will 
96e0: 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65  never be extende
96f0: 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61  d.  It will alwa
9700: 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79  ys.** be exactly
9710: 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e   zero..*/.#defin
9720: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
9730: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
9740: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
9750: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
9760: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
9770: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
9780: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9790: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
97a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
97b0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
97c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
97d0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
97e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
97f0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
9800: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
9810: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9820: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
9830: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
9840: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
9850: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9860: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
9870: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
9880: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
9890: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
98a0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
98b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
98c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
98d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
98e0: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
98f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9900: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
9910: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
9920: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
9930: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
9940: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
9950: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9960: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
9970: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9980: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
9990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
99a0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
99b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
99c0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
99d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
99e0: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
99f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9a00: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
9a10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9a20: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
9a30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9a40: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
9a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9a60: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
9a70: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
9a80: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
9a90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9aa0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
9ab0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9ac0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
9ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9ae0: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
9af0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9b00: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
9b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9b20: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
9b30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9b40: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
9b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9b60: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20  IOERR_SHMOPEN   
9b70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9b80: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29  IOERR | (18<<8))
9b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9ba0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20  IOERR_SHMSIZE   
9bb0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9bc0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29  IOERR | (19<<8))
9bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9be0: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20  IOERR_SHMLOCK   
9bf0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9c00: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29  IOERR | (20<<8))
9c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9c20: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20  IOERR_SHMMAP    
9c30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9c40: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29  IOERR | (21<<8))
9c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9c60: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20  IOERR_SEEK      
9c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9c80: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29  IOERR | (22<<8))
9c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9ca0: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43  LOCKED_SHAREDCAC
9cb0: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  HE      (SQLITE_
9cc0: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29  LOCKED |  (1<<8)
9cd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
9ce0: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20  _BUSY_RECOVERY  
9cf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
9d00: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38  _BUSY   |  (1<<8
9d10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9d20: 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d  E_CANTOPEN_NOTEM
9d30: 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54  PDIR      (SQLIT
9d40: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c  E_CANTOPEN | (1<
9d50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9d60: 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42  ITE_CORRUPT_VTAB
9d70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9d80: 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31  ITE_CORRUPT | (1
9d90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9da0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45  LITE_READONLY_RE
9db0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51  COVERY       (SQ
9dc0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
9dd0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
9de0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
9df0: 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28  CANTLOCK       (
9e00: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
9e10: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
9e20: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
9e30: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
9e40: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
9e50: 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (2<<8))../*.** 
9e60: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
9e70: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
9e80: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
9e90: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
9ea0: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
9eb0: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
9ec0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
9ed0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
9ee0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
9ef0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
9f00: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
9f10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
9f20: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
9f30: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
9f40: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
9f50: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
9f60: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
9f70: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
9f80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
9f90: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
9fa0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
9fb0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
9fc0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
9fd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
9fe0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
9ff0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
a000: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
a010: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
a020: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a030: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
a040: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
a050: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
a060: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a070: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
a080: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
a090: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
a0a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a0b0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
a0c0: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
a0d0: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
a0e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a0f0: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
a100: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
a110: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
a120: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
a130: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a140: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
a150: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
a160: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
a170: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a180: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
a190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
a1a0: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
a1b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a1c0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
a1d0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
a1e0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
a1f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a200: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
a210: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
a220: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
a230: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a240: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
a250: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
a260: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
a270: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a280: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
a290: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
a2a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
a2b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a2c0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
a2d0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
a2e0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
a2f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a300: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
a310: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
a320: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
a330: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
a340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a350: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
a360: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
a370: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
a380: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
a390: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a3a0: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
a3b0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
a3c0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
a3d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
a3e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a3f0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
a400: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
a410: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
a420: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
a430: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a440: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
a450: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
a460: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
a470: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
a480: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
a490: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
a4a0: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
a4b0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
a4c0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
a4d0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
a4e0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a4f0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
a500: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
a510: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
a520: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
a530: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
a540: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a  or of the these.
a550: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
a560: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
a570: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
a580: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
a590: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
a5a0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
a5b0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
a5c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
a5d0: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
a5e0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
a5f0: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
a600: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
a610: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
a620: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
a630: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
a640: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
a650: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
a660: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
a670: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
a680: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
a690: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
a6a0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
a6b0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
a6c0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
a6d0: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
a6e0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
a6f0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
a700: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
a710: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
a720: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
a730: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
a740: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
a750: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
a760: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
a770: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
a780: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
a790: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
a7a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
a7b0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
a7c0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
a7d0: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
a7e0: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
a7f0: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
a800: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
a810: 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c  rite().  The SQL
a820: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
a830: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72  AFE_OVERWRITE pr
a840: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
a850: 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f  t.** after reboo
a860: 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  t following a cr
a870: 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73  ash or power los
a880: 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65  s, the only byte
a890: 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74  s in a.** file t
a8a0: 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e  hat were written
a8b0: 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74   at the applicat
a8c0: 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20  ion level might 
a8d0: 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  have changed.** 
a8e0: 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e  and that adjacen
a8f0: 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79  t bytes, even by
a900: 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  tes within the s
a910: 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a  ame sector are.*
a920: 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  * guaranteed to 
a930: 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f  be unchanged..*/
a940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a950: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
a960: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
a970: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
a980: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a990: 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20  MIC512          
a9a0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
a9b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
a9c0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20  CAP_ATOMIC1K    
a9d0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
a9e0: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
a9f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
aa00: 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C2K             
aa10: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
aa20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
aa30: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20  P_ATOMIC4K      
aa40: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
aa50: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
aa60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
aa70: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
aa80: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
aa90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
aaa0: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
aab0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
aac0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
aad0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
aae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
aaf0: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65  00000080.#define
ab00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
ab10: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20  OMIC64K         
ab20: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
ab30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
ab40: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
ab50: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
ab60: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
ab70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
ab80: 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20  ENTIAL          
ab90: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64     0x00000400.#d
aba0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
abb0: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
abc0: 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30  HEN_OPEN  0x0000
abd0: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
abe0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
abf0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
ac00: 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a   0x00001000../*.
ac10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
ac20: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
ac30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
ac40: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
ac50: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
ac60: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
ac70: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
ac80: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
ac90: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
aca0: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
acb0: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
acc0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
acd0: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
ace0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
acf0: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
ad00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
ad10: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
ad20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ad30: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
ad40: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
ad50: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
ad60: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
ad70: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
ad80: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
ad90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
ada0: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
adb0: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
adc0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
add0: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
ade0: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
adf0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
ae00: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
ae10: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
ae20: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
ae30: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
ae40: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
ae50: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
ae60: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
ae70: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
ae80: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
ae90: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
aea0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
aeb0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
aec0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
aed0: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
aee0: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
aef0: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
af00: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
af10: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
af20: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
af30: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
af40: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
af50: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
af60: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
af70: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
af80: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
af90: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
afa0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
afb0: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
afc0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
afd0: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
afe0: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
aff0: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
b000: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
b010: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
b020: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
b030: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
b040: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
b050: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
b060: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
b070: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
b080: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
b090: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
b0a0: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
b0b0: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
b0c0: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
b0d0: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
b0e0: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
b0f0: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
b100: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
b110: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
b120: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
b130: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
b140: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
b150: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
b160: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
b170: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
b180: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
b190: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
b1a0: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
b1b0: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
b1c0: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
b1d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
b1e0: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
b1f0: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
b200: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
b210: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
b220: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
b230: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
b240: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
b250: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
b260: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
b270: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
b280: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
b290: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
b2a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
b2b0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
b2c0: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
b2d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
b2e0: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
b2f0: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
b300: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
b310: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
b320: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
b330: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
b340: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
b350: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
b360: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
b370: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
b380: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
b390: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
b3a0: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
b3b0: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
b3c0: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
b3d0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
b3e0: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
b3f0: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
b400: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
b410: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
b420: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
b430: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
b440: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
b450: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
b460: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
b470: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
b480: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
b490: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
b4a0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
b4b0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
b4c0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
b4d0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
b4e0: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
b4f0: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
b500: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
b510: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
b520: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
b530: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
b540: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
b550: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
b560: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
b570: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
b580: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
b590: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
b5a0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
b5b0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
b5c0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
b5d0: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
b5e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
b5f0: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
b600: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
b610: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
b620: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
b630: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
b640: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
b650: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
b660: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
b670: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
b680: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
b690: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
b6a0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
b6b0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
b6c0: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
b6d0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
b6e0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
b6f0: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
b700: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
b710: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
b720: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
b730: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
b740: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
b750: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
b760: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
b770: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
b780: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
b790: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
b7a0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
b7b0: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
b7c0: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
b7d0: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
b7e0: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
b7f0: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
b800: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
b810: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
b820: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
b830: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
b840: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
b850: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
b860: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
b870: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
b880: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
b890: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
b8a0: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
b8b0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
b8c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
b8d0: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
b8e0: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
b8f0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
b900: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
b910: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
b920: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
b930: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
b940: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
b950: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
b960: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
b970: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
b980: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
b990: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
b9a0: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
b9b0: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
b9c0: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
b9d0: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
b9e0: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
b9f0: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
ba00: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
ba10: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
ba20: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
ba30: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
ba40: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
ba50: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
ba60: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
ba70: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
ba80: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
ba90: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
baa0: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
bab0: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
bac0: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
bad0: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
bae0: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
baf0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
bb00: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
bb10: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
bb20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
bb30: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
bb40: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
bb50: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
bb60: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
bb70: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
bb80: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
bb90: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
bba0: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
bbb0: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
bbc0: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
bbd0: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
bbe0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
bbf0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
bc00: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
bc10: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
bc20: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
bc30: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
bc40: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
bc50: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
bc60: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
bc70: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
bc80: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
bc90: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
bca0: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
bcb0: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
bcc0: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
bcd0: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
bce0: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
bcf0: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
bd00: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
bd10: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
bd20: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
bd30: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
bd40: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
bd50: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
bd60: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
bd70: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
bd80: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
bd90: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
bda0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
bdb0: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
bdc0: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
bdd0: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
bde0: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
bdf0: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
be00: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
be10: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
be20: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
be30: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
be40: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
be50: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
be60: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
be70: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
be80: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
be90: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
bea0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
beb0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
bec0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
bed0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
bee0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
bef0: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
bf00: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
bf10: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
bf20: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
bf30: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
bf40: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
bf50: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
bf60: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
bf70: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
bf80: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
bf90: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
bfa0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
bfb0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
bfc0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
bfd0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
bfe0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
bff0: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
c000: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
c010: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
c020: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
c030: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
c040: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
c050: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
c060: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
c070: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
c080: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
c090: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
c0a0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
c0b0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
c0c0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
c0d0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
c0e0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
c0f0: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
c100: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
c110: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
c120: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
c130: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
c140: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
c150: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
c160: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
c170: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
c180: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
c190: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
c1a0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
c1b0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
c1c0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
c1d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
c1e0: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
c1f0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
c200: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
c210: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
c220: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
c230: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
c240: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
c250: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
c260: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
c270: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
c280: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
c290: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
c2a0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
c2b0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
c2c0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
c2d0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
c2e0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
c2f0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
c300: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
c310: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
c320: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
c330: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
c340: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
c350: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
c360: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
c370: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
c380: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
c390: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
c3a0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
c3b0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
c3c0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
c3d0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
c3e0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
c3f0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
c400: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
c410: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
c420: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
c430: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
c440: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
c450: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
c460: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
c470: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
c480: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
c490: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
c4a0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
c4b0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
c4c0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
c4d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
c4e0: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
c4f0: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
c500: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
c510: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
c520: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
c530: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
c540: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
c550: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
c560: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
c570: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
c580: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
c590: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
c5a0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
c5b0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
c5c0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
c5d0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
c5e0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
c5f0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
c600: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
c610: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
c620: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
c630: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
c640: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
c650: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
c660: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
c670: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
c680: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
c690: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
c6a0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
c6b0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
c6c0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
c6d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
c6e0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
c6f0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
c700: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
c710: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
c720: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
c730: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
c740: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
c750: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
c760: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
c770: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
c780: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
c790: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
c7a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
c7b0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
c7c0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
c7d0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
c7e0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
c7f0: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
c800: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
c810: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
c820: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
c830: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
c840: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
c850: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
c860: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
c870: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
c880: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
c890: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
c8a0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
c8b0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
c8c0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
c8d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
c8e0: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
c8f0: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
c900: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
c910: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
c920: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
c930: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
c940: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
c950: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
c960: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
c970: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
c980: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
c990: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
c9a0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
c9b0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
c9c0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
c9d0: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
c9e0: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
c9f0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
ca00: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
ca10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
ca20: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
ca30: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a  trol Opcodes.**.
ca40: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
ca50: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f   constants are o
ca60: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78  pcodes for the x
ca70: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
ca80: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  od.** of the [sq
ca90: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
caa0: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72  ] object and for
cab0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
cac0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a  le_control()].**
cad0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
cae0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
caf0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
cb00: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
cb10: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
cb20: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
cb30: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
cb40: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
cb50: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
cb60: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
cb70: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
cb80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
cb90: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
cba0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
cbb0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
cbc0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
cbd0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
cbe0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
cbf0: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
cc00: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
cc10: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
cc20: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
cc30: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
cc40: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
cc50: 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  ting and only ne
cc60: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
cc70: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
cc80: 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e  TEST.** is defin
cc90: 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ed..** <ul>.** <
cca0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ccb0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a  L_SIZE_HINT]].**
ccc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
ccd0: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70  TL_SIZE_HINT] op
cce0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20  code is used by 
ccf0: 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74  SQLite to give t
cd00: 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20  he VFS.** layer 
cd10: 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61  a hint of how la
cd20: 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  rge the database
cd30: 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20   file will grow 
cd40: 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65  to be during the
cd50: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e  .** current tran
cd60: 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68  saction.  This h
cd70: 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61  int is not guara
cd80: 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75  nteed to be accu
cd90: 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69  rate but it.** i
cda0: 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20  s often close.  
cdb0: 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56  The underlying V
cdc0: 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20  FS might choose 
cdd0: 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64  to preallocate d
cde0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
cdf0: 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74  space based on t
ce00: 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65  his hint in orde
ce10: 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73  r to help writes
ce20: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
ce30: 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73  .** file run fas
ce40: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
ce50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
ce60: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  UNK_SIZE]].** Th
ce70: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ce80: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
ce90: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
cea0: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
ceb0: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
cec0: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
ced0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
cee0: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
cef0: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
cf00: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
cf10: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
cf20: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
cf30: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
cf40: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
cf50: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
cf60: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
cf70: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
cf80: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
cf90: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
cfa0: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
cfb0: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
cfc0: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
cfd0: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
cfe0: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
cff0: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
d000: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
d010: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
d020: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
d030: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
d040: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
d050: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
d060: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
d070: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
d080: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  ILE_POINTER] opc
d090: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
d0a0: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
d0b0: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
d0c0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
d0d0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
d0e0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
d0f0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
d100: 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73  ion.  See the [s
d110: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
d120: 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61  rol()] documenta
d130: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69  tion for.** addi
d140: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
d150: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  on..**.** <li>[[
d160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
d170: 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e  C_OMITTED]].** ^
d180: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  (The [SQLITE_FCN
d190: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
d1a0: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
d1b0: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
d1c0: 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64  by.** SQLite and
d1d0: 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53   sent to all VFS
d1e0: 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61  es in place of a
d1f0: 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79   call to the xSy
d200: 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65  nc method.** whe
d210: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
d220: 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50  onnection has [P
d230: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
d240: 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e  s] set to OFF.)^
d250: 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c  .** Some special
d260: 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20  ized VFSes need 
d270: 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f  this signal in o
d280: 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20  rder to operate 
d290: 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65  correctly.** whe
d2a0: 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  n [PRAGMA synchr
d2b0: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73  onous | PRAGMA s
d2c0: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20  ynchronous=OFF] 
d2d0: 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74  is set, but most
d2e0: 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f   .** VFSes do no
d2f0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
d300: 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69  al and should si
d310: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
d320: 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70  is opcode..** Ap
d330: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
d340: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
d350: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
d360: 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a  ()] with this.**
d370: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
d380: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
d390: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  the operation of
d3a0: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
d3b0: 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64   VFSes.** that d
d3c0: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
d3d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
d3e0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
d3f0: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
d400: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
d410: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
d420: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
d430: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
d440: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
d450: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
d460: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
d470: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
d480: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
d490: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
d4a0: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
d4b0: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
d4c0: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
d4d0: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
d4e0: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
d4f0: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
d500: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
d510: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
d520: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
d530: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
d540: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
d550: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
d560: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
d570: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
d580: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
d590: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
d5a0: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
d5b0: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
d5c0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
d5d0: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
d5e0: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
d5f0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
d600: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
d610: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
d620: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
d630: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
d640: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
d650: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
d660: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
d670: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
d680: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
d690: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
d6a0: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
d6b0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
d6c0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
d6d0: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
d6e0: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
d6f0: 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65  ger i the new re
d700: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
d710: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
d720: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
d730: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
d740: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
d750: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
d760: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
d770: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
d780: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
d790: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
d7a0: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
d7b0: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
d7c0: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
d7d0: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
d7e0: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
d7f0: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
d800: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
d810: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
d820: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
d830: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
d840: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
d850: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
d860: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
d870: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
d880: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
d890: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
d8a0: 41 4c 20 7c 20 57 72 69 74 65 20 41 48 65 61 64  AL | Write AHead
d8b0: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
d8c0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
d8d0: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
d8e0: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64  te ahead log and
d8f0: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
d900: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
d910: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
d920: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
d930: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
d940: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
d950: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
d960: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
d970: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
d980: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
d990: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
d9a0: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
d9b0: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
d9c0: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
d9d0: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
d9e0: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
d9f0: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
da00: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
da10: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
da20: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
da30: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
da40: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
da50: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
da60: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
da70: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
da80: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
da90: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
daa0: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
dab0: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
dac0: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
dad0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
dae0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
daf0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
db00: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
db10: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
db20: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
db30: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
db40: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
db50: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
db60: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
db70: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
db80: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
db90: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
dba0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
dbb0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
dbc0: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
dbd0: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
dbe0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
dbf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
dc00: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
dc10: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
dc20: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
dc30: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
dc40: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
dc50: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
dc60: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
dc70: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
dc80: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
dc90: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
dca0: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
dcb0: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
dcc0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
dcd0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
dce0: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
dcf0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
dd00: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
dd10: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
dd20: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
dd30: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
dd40: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
dd50: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
dd60: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
dd70: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
dd80: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
dd90: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
dda0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
ddb0: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
ddc0: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
ddd0: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
dde0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
ddf0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
de00: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
de10: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
de20: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
de30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
de40: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
de50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
de60: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
de70: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
de80: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
de90: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
dea0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
deb0: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
dec0: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
ded0: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
dee0: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
def0: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
df00: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
df10: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
df20: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
df30: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
df40: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
df50: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
df60: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
df70: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
df80: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
df90: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
dfa0: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
dfb0: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
dfc0: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
dfd0: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
dfe0: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
dff0: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
e000: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
e010: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
e020: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
e030: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
e040: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
e050: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
e060: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
e070: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
e080: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
e090: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
e0a0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
e0b0: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
e0c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
e0d0: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
e0e0: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
e0f0: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
e100: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
e110: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
e120: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
e130: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
e140: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
e150: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
e160: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
e170: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
e180: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
e190: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
e1a0: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
e1b0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
e1c0: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
e1d0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
e1e0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
e1f0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
e200: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
e210: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
e220: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
e230: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
e240: 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57  L_PRAGMA]].** ^W
e250: 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d  henever a [PRAGM
e260: 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  A] statement is 
e270: 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49  parsed, an [SQLI
e280: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
e290: 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f   .** file contro
e2a0: 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65  l is sent to the
e2b0: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   open [sqlite3_f
e2c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72  ile] object corr
e2d0: 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20  esponding.** to 
e2e0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
e2f0: 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70  e to which the p
e300: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
e310: 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67  refers. ^The arg
e320: 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
e330: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
e340: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
e350: 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ol is an array o
e360: 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  f.** pointers to
e370: 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a   strings (char**
e380: 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73  ) in which the s
e390: 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66  econd element of
e3a0: 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73   the array.** is
e3b0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
e3c0: 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20   pragma and the 
e3d0: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73  third element is
e3e0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
e3f0: 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f   the.** pragma o
e400: 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72  r NULL if the pr
e410: 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75  agma has no argu
e420: 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64  ment.  ^The hand
e430: 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53  ler for an.** [S
e440: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
e450: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
e460: 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   can optionally 
e470: 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65  make the first e
e480: 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65  lement.** of the
e490: 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74   char** argument
e4a0: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
e4b0: 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
e4c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
e4d0: 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65  f()].** or the e
e4e0: 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68  quivalent and th
e4f0: 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  at string will b
e500: 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74  ecome the result
e510: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f   of the pragma o
e520: 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  r.** the error m
e530: 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72  essage if the pr
e540: 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20  agma fails. ^If 
e550: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
e560: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
e570: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
e580: 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  s [SQLITE_NOTFOU
e590: 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c  ND], then normal
e5a0: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72   .** [PRAGMA] pr
e5b0: 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75  ocessing continu
e5c0: 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  es.  ^If the [SQ
e5d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
e5e0: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
e5f0: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
e600: 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65  TE_OK], then the
e610: 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20   parser assumes 
e620: 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20  that the.** VFS 
e630: 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20  has handled the 
e640: 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e  PRAGMA itself an
e650: 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e  d the parser gen
e660: 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a  erates a no-op.*
e670: 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
e680: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b  ment.  ^If the [
e690: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
e6a0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
e6b0: 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  l returns.** any
e6c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68   result code oth
e6d0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
e6e0: 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  OK] or [SQLITE_N
e6f0: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d  OTFOUND], that m
e700: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  eans.** that the
e710: 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64   VFS encountered
e720: 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20   an error while 
e730: 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52  handling the [PR
e740: 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  AGMA] and the.**
e750: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20   compilation of 
e760: 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73  the PRAGMA fails
e770: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
e780: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
e790: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
e7a0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75  ile control occu
e7b0: 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e  rs at the beginn
e7c0: 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74  ing of pragma st
e7d0: 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73  atement analysis
e7e0: 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73   and so.** it is
e7f0: 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64   able to overrid
e800: 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47  e built-in [PRAG
e810: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  MA] statements..
e820: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
e830: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e840: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
e850: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
e860: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
e870: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
e880: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
e890: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
e8a0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
e8b0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
e8c0: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
e8d0: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
e8e0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
e8f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
e900: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
e910: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
e920: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
e930: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
e940: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
e950: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
e960: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
e970: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
e980: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
e990: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
e9a0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
e9b0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
e9c0: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
e9d0: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
e9e0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
e9f0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
ea00: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
ea10: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
ea20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
ea30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ea40: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
ea50: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
ea60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ea70: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
ea80: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
ea90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
eaa0: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
eab0: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 0a 2f             14../
eac0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
ead0: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
eae0: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
eaf0: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
eb00: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
eb10: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
eb20: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
eb30: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
eb40: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
eb50: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
eb60: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
eb70: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
eb80: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
eb90: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
eba0: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
ebb0: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
ebc0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
ebd0: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
ebe0: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
ebf0: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
ec00: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
ec10: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
ec20: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
ec30: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
ec40: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
ec50: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
ec60: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
ec70: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
ec80: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
ec90: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
eca0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
ecb0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
ecc0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
ecd0: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
ece0: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
ecf0: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
ed00: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
ed10: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
ed20: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
ed30: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
ed40: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
ed50: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
ed60: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
ed70: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
ed80: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
ed90: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
eda0: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
edb0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
edc0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
edd0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
ede0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
edf0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
ee00: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
ee10: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
ee20: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
ee30: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
ee40: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
ee50: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
ee60: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
ee70: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
ee80: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
ee90: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
eea0: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
eeb0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
eec0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
eed0: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
eee0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
eef0: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
ef00: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
ef10: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
ef20: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
ef30: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
ef40: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
ef50: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
ef60: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
ef70: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
ef80: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
ef90: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
efa0: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
efb0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
efc0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
efd0: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
efe0: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
eff0: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
f000: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
f010: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
f020: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
f030: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
f040: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
f050: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
f060: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
f070: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
f080: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
f090: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
f0a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
f0b0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
f0c0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f0d0: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
f0e0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
f0f0: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
f100: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
f110: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
f120: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
f130: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
f140: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
f150: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
f160: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
f170: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
f180: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
f190: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
f1a0: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
f1b0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
f1c0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
f1d0: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
f1e0: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
f1f0: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
f200: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
f210: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
f220: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
f230: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
f240: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
f250: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
f260: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
f270: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
f280: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
f290: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
f2a0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
f2b0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
f2c0: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
f2d0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
f2e0: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
f2f0: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
f300: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
f310: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
f320: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
f330: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
f340: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
f350: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
f360: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
f370: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
f380: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
f390: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
f3a0: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
f3b0: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
f3c0: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
f3d0: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
f3e0: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
f3f0: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
f400: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
f410: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
f420: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
f430: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
f440: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
f450: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
f460: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
f470: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
f480: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
f490: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
f4a0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
f4b0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
f4c0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
f4d0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
f4e0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
f4f0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
f500: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
f510: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
f520: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
f530: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
f540: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
f550: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
f560: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
f570: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
f580: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
f590: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
f5a0: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
f5b0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
f5c0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
f5d0: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
f5e0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
f5f0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
f600: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
f610: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
f620: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
f630: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
f640: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
f650: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
f660: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
f670: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
f680: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
f690: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
f6a0: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
f6b0: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
f6c0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
f6d0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
f6e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
f6f0: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
f700: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
f710: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
f720: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
f730: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
f740: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
f750: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
f760: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
f770: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
f780: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
f790: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
f7a0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
f7b0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
f7c0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
f7d0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
f7e0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
f7f0: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
f800: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
f810: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
f820: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
f830: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
f840: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
f850: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
f860: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
f870: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
f880: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
f890: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
f8a0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
f8b0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
f8c0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
f8d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
f8e0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
f8f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
f900: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
f910: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
f920: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
f930: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
f940: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
f950: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
f960: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
f970: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
f980: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
f990: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
f9a0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
f9b0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
f9c0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
f9d0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
f9e0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
f9f0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
fa00: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
fa10: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
fa20: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
fa30: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
fa40: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
fa50: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
fa60: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
fa70: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
fa80: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
fa90: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
faa0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
fab0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
fac0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
fad0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
fae0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
faf0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
fb00: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
fb10: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
fb20: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
fb30: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
fb40: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
fb50: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
fb60: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
fb70: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
fb80: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
fb90: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
fba0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
fbb0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
fbc0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
fbd0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
fbe0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
fbf0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
fc00: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
fc10: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
fc20: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
fc30: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
fc40: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
fc50: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
fc60: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
fc70: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
fc80: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
fc90: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
fca0: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
fcb0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
fcc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
fcd0: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
fce0: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
fcf0: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
fd00: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
fd10: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
fd20: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
fd30: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
fd40: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
fd50: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
fd60: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
fd70: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
fd80: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
fd90: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
fda0: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
fdb0: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
fdc0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
fdd0: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
fde0: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
fdf0: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
fe00: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
fe10: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
fe20: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
fe30: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
fe40: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
fe50: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
fe60: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
fe70: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
fe80: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
fe90: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
fea0: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
feb0: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
fec0: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
fed0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
fee0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
fef0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
ff00: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
ff10: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
ff20: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
ff30: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
ff40: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
ff50: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
ff60: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
ff70: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
ff80: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
ff90: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
ffa0: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
ffb0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
ffc0: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
ffd0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
ffe0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
fff0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
10000 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
10010 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
10020 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
10030 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
10040 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
10050 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
10060 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
10070 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
10080 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
10090 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
100a0 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
100b0 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
100c0 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
100d0 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
100e0 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
100f0 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
10100 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
10110 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
10120 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
10130 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
10140 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
10150 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
10160 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
10170 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
10180 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
10190 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
101a0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
101b0 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
101c0 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
101d0 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
101e0 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
101f0 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
10200 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
10210 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
10220 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
10230 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
10240 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
10250 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
10260 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
10270 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
10280 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
10290 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
102a0 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
102b0 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
102c0 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
102d0 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
102e0 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
102f0 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
10300 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
10310 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
10320 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
10330 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
10340 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
10350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
10360 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
10370 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
10380 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
10390 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
103a0 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
103b0 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
103c0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
103d0 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
103e0 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
103f0 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
10400 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
10410 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
10420 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
10430 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
10440 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
10450 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
10460 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
10470 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
10480 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
10490 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
104a0 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
104b0 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
104c0 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
104d0 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
104e0 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
104f0 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
10500 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
10510 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
10520 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
10530 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
10540 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
10550 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
10560 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
10570 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
10580 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
10590 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
105a0 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
105b0 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
105c0 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
105d0 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
105e0 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
105f0 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
10600 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
10610 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
10620 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
10630 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
10640 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
10650 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
10660 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
10670 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
10680 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
10690 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
106a0 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
106b0 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
106c0 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
106d0 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
106e0 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
106f0 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
10700 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
10710 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
10720 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
10730 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
10740 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
10750 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
10760 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
10770 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
10780 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
10790 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
107a0 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
107b0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
107c0 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
107d0 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
107e0 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
107f0 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
10800 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
10810 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
10820 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
10830 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
10840 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
10850 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
10860 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
10870 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
10880 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
10890 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
108a0 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
108b0 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
108c0 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
108d0 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
108e0 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
108f0 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
10900 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
10910 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
10920 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
10930 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
10940 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
10950 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
10960 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
10970 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
10980 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
10990 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
109a0 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
109b0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
109c0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
109d0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
109e0 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
109f0 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
10a00 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
10a10 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
10a20 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10a30 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
10a40 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
10a50 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
10a60 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
10a70 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
10a80 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
10a90 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
10aa0 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
10ab0 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
10ac0 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
10ad0 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
10ae0 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
10af0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
10b00 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
10b10 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
10b20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
10b30 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
10b40 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
10b50 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
10b60 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
10b70 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
10b80 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
10b90 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
10ba0 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
10bb0 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
10bc0 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
10bd0 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
10be0 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
10bf0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
10c00 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
10c10 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
10c20 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
10c30 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
10c40 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
10c50 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
10c60 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
10c70 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
10c80 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
10c90 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
10ca0 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
10cb0 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
10cc0 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
10cd0 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
10ce0 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
10cf0 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
10d00 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
10d10 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
10d20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
10d30 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
10d40 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
10d50 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10d60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
10d70 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
10d80 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
10d90 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10da0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
10db0 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
10dc0 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
10dd0 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
10de0 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
10df0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
10e00 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
10e10 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
10e20 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
10e30 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10e40 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
10e50 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
10e60 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
10e70 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
10e80 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
10e90 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
10ea0 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
10eb0 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
10ec0 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
10ed0 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
10ee0 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
10ef0 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
10f00 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
10f10 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
10f20 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
10f30 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
10f40 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
10f50 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
10f60 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
10f70 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
10f80 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
10f90 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
10fa0 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
10fb0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
10fc0 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
10fd0 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
10fe0 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
10ff0 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
11000 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
11010 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
11020 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
11030 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
11040 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
11050 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
11060 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
11070 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
11080 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
11090 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
110a0 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
110b0 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
110c0 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
110d0 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
110e0 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
110f0 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
11100 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
11110 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
11120 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
11130 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
11140 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
11150 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
11160 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
11170 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
11180 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
11190 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
111a0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
111b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
111c0 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
111d0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
111e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
111f0 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
11200 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
11210 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
11220 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
11230 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
11240 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
11250 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
11260 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
11270 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
11280 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
11290 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
112a0 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
112b0 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
112c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
112d0 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
112e0 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
112f0 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
11300 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
11310 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
11320 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
11330 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
11340 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
11350 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
11360 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
11370 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
11380 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
11390 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
113a0 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
113b0 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
113c0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
113d0 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
113e0 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
113f0 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
11400 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
11410 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
11420 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
11430 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
11440 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
11450 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
11460 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
11470 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
11480 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
11490 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
114a0 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
114b0 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
114c0 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
114d0 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
114e0 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
114f0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
11500 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
11510 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
11520 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
11530 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
11540 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
11550 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
11560 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
11570 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
11580 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
11590 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
115a0 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
115b0 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
115c0 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
115d0 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
115e0 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
115f0 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
11600 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
11610 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
11620 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
11630 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
11640 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
11650 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
11660 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
11670 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
11680 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
11690 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
116a0 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
116b0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
116c0 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
116d0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
116e0 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
116f0 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
11700 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
11710 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
11720 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
11730 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
11740 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
11750 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
11760 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
11770 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
11780 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
11790 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
117a0 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
117b0 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
117c0 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
117d0 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
117e0 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
117f0 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
11800 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
11810 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
11820 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
11830 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
11840 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
11850 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
11860 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
11870 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
11880 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
11890 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
118a0 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
118b0 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
118c0 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
118d0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
118e0 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
118f0 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
11900 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
11910 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
11920 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
11930 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
11940 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
11950 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
11960 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
11970 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
11980 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
11990 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
119a0 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
119b0 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
119c0 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
119d0 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
119e0 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
119f0 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
11a00 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
11a10 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
11a20 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
11a30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
11a40 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
11a50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11a60 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
11a70 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
11a80 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
11a90 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
11aa0 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
11ab0 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
11ac0 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
11ad0 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
11ae0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
11af0 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
11b00 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
11b10 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
11b20 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
11b30 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
11b40 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
11b50 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
11b60 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
11b70 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
11b80 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
11b90 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
11ba0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
11bb0 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
11bc0 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
11bd0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
11be0 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
11bf0 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
11c00 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
11c10 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
11c20 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
11c30 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
11c40 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
11c50 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
11c60 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
11c70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
11c80 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
11c90 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
11ca0 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
11cb0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
11cc0 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
11cd0 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
11ce0 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
11cf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
11d00 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
11d10 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
11d20 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
11d30 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
11d40 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
11d50 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
11d60 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
11d70 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
11d80 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
11d90 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
11da0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11db0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
11dc0 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
11dd0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
11de0 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
11df0 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
11e00 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11e10 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
11e20 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
11e30 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
11e40 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
11e50 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
11e60 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
11e70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11e80 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
11e90 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
11ea0 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
11eb0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
11ec0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
11ed0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
11ee0 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
11ef0 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
11f00 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
11f10 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
11f20 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
11f30 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
11f40 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11f50 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
11f60 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
11f70 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
11f80 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
11f90 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
11fa0 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
11fb0 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
11fc0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11fd0 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
11fe0 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
11ff0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
12000 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
12010 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
12020 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
12030 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
12040 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
12050 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
12060 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
12070 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
12080 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
12090 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
120a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
120b0 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
120c0 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
120d0 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
120e0 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
120f0 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
12100 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
12110 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
12120 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
12130 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
12140 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12150 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
12160 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
12170 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
12180 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12190 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
121a0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
121b0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
121c0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
121d0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
121e0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
121f0 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
12200 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
12210 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
12220 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
12230 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
12240 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
12250 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
12260 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
12270 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
12280 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
12290 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
122a0 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
122b0 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
122c0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
122d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
122e0 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
122f0 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
12300 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
12310 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
12320 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
12330 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
12340 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
12350 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
12360 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
12370 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
12380 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
12390 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
123a0 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
123b0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
123c0 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
123d0 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
123e0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
123f0 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
12400 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
12410 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
12420 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
12430 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
12440 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
12450 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12460 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
12470 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
12480 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
12490 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
124a0 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
124b0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
124c0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
124d0 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
124e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
124f0 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
12500 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12510 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
12520 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
12530 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
12540 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
12550 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
12560 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
12570 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
12580 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
12590 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
125a0 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
125b0 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
125c0 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
125d0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
125e0 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
125f0 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
12600 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
12610 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
12620 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
12630 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
12640 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
12650 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
12660 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
12670 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
12680 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
12690 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
126a0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
126b0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
126c0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
126d0 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
126e0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
126f0 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
12700 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
12710 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
12720 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
12730 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
12740 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
12750 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
12760 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
12770 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
12780 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
12790 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
127a0 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
127b0 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
127c0 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
127d0 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
127e0 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
127f0 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
12800 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
12810 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
12820 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
12830 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
12840 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
12850 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
12860 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
12870 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
12880 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
12890 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
128a0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
128b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
128c0 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
128d0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
128e0 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
128f0 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
12900 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
12910 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12920 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
12930 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
12940 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
12950 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
12960 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
12970 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
12980 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
12990 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
129a0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
129b0 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
129c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
129d0 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
129e0 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
129f0 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
12a00 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
12a10 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
12a20 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
12a30 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
12a40 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
12a50 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
12a60 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
12a70 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
12a80 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
12a90 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
12aa0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
12ab0 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
12ac0 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
12ad0 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
12ae0 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
12af0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
12b00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
12b10 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
12b20 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
12b30 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
12b40 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
12b50 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
12b60 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
12b70 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
12b80 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
12b90 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
12ba0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
12bb0 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
12bc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
12bd0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12be0 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ze(void);.SQLITE
12bf0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
12c00 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
12c10 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
12c20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
12c30 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
12c40 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  I int sqlite3_os
12c50 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
12c60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
12c70 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
12c80 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
12c90 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
12ca0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
12cb0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
12cc0 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
12cd0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
12ce0 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
12cf0 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
12d00 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
12d10 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
12d20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
12d30 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
12d40 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
12d50 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
12d60 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
12d70 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
12d80 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
12d90 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
12da0 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
12db0 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
12dc0 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
12dd0 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
12de0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
12df0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
12e00 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
12e10 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
12e20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
12e30 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
12e40 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
12e50 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
12e60 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
12e70 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
12e80 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
12e90 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
12ea0 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
12eb0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
12ec0 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
12ed0 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
12ee0 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
12ef0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
12f00 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12f10 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
12f20 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
12f30 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
12f40 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
12f50 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
12f60 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
12f70 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
12f80 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
12f90 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12fa0 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
12fb0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
12fc0 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
12fd0 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
12fe0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
12ff0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
13000 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
13010 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
13020 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
13030 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
13040 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
13050 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
13060 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
13070 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
13080 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
13090 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
130a0 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
130b0 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
130c0 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
130d0 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
130e0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
130f0 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
13100 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
13110 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
13120 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
13130 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13140 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
13150 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13160 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
13170 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
13180 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
13190 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
131a0 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
131b0 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
131c0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
131d0 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
131e0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
131f0 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
13200 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53  rror code]..*/.S
13210 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
13220 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
13230 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
13240 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
13250 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
13260 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  ections.**.** Th
13270 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
13280 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
13290 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
132a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
132b0 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
132c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
132d0 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
132e0 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
132f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13300 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
13310 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
13320 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
13330 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
13340 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
13350 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
13360 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
13370 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
13380 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
13390 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
133a0 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
133b0 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
133c0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
133d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
133e0 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
133f0 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
13400 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
13410 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
13420 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13430 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
13440 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
13450 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
13460 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
13470 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
13480 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
13490 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
134a0 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
134b0 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
134c0 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
134d0 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
134e0 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
134f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
13500 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
13510 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
13520 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
13530 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
13540 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
13550 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
13560 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
13570 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
13580 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
13590 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
135a0 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
135b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
135c0 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
135d0 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
135e0 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
135f0 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
13600 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
13610 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
13620 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
13630 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
13640 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
13650 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13660 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
13670 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13680 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
13690 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
136a0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
136b0 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
136c0 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
136d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
136e0 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
136f0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
13700 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
13710 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13720 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
13730 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
13740 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
13750 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
13760 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
13770 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13780 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
13790 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
137a0 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
137b0 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
137c0 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
137d0 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
137e0 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
137f0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
13800 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
13810 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
13820 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
13830 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
13840 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
13850 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
13860 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
13870 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
13880 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
13890 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
138a0 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
138b0 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
138c0 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
138d0 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
138e0 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
138f0 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
13900 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
13910 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
13920 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
13930 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
13940 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
13950 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
13960 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
13970 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
13980 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
13990 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
139a0 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
139b0 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
139c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
139d0 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
139e0 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
139f0 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
13a00 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
13a10 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
13a20 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
13a30 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
13a40 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
13a50 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
13a60 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
13a70 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
13a80 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
13a90 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
13aa0 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
13ab0 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
13ac0 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
13ad0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
13ae0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
13af0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
13b00 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
13b10 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
13b20 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
13b30 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
13b40 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
13b50 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
13b60 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
13b70 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
13b80 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
13b90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
13ba0 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
13bb0 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
13bc0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
13bd0 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
13be0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
13bf0 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
13c00 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
13c10 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
13c20 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
13c30 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
13c40 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
13c50 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
13c60 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
13c70 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
13c80 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
13c90 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
13ca0 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
13cb0 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
13cc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
13cd0 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
13ce0 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
13cf0 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
13d00 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
13d10 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
13d20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
13d30 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
13d40 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
13d50 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
13d60 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
13d70 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
13d80 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
13d90 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
13da0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
13db0 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
13dc0 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
13dd0 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
13de0 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
13df0 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
13e00 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
13e10 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
13e20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
13e30 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
13e40 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
13e50 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
13e60 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
13e70 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
13e80 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
13e90 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
13ea0 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
13eb0 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
13ec0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
13ed0 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
13ee0 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
13ef0 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
13f00 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
13f10 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
13f20 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
13f30 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
13f40 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
13f50 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
13f60 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
13f70 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
13f80 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
13f90 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
13fa0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
13fb0 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
13fc0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
13fd0 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
13fe0 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
13ff0 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
14000 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
14010 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
14020 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
14030 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
14040 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
14050 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
14060 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
14070 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
14080 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
14090 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
140a0 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
140b0 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
140c0 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
140d0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
140e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
140f0 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
14100 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
14110 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
14120 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
14130 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
14140 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
14150 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
14160 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
14170 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
14180 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
14190 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
141a0 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
141b0 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
141c0 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
141d0 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
141e0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
141f0 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
14200 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
14210 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
14220 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
14230 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
14240 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
14250 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14260 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
14270 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
14280 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
14290 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
142a0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
142b0 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
142c0 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
142d0 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
142e0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
142f0 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
14300 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
14310 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
14320 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
14330 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
14340 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
14350 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
14360 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
14370 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
14380 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
14390 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
143a0 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
143b0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
143c0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
143d0 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
143e0 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
143f0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
14400 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
14410 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
14420 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
14430 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
14440 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
14450 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
14460 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
14470 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
14480 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
14490 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
144a0 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
144b0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
144c0 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
144d0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
144e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
144f0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
14500 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
14510 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
14520 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
14530 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
14540 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
14550 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
14560 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
14570 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
14580 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
14590 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
145a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
145b0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
145c0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
145d0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
145e0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
145f0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
14600 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
14610 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
14620 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
14630 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
14640 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
14650 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
14660 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
14670 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
14680 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
14690 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
146a0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
146b0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
146c0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
146d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
146e0 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
146f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
14700 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
14710 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
14720 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
14730 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
14740 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
14750 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
14760 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
14770 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
14780 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
14790 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
147a0 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
147b0 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
147c0 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
147d0 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
147e0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
147f0 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
14800 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
14810 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
14820 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
14830 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
14840 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
14850 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
14860 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
14870 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
14880 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
14890 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
148a0 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
148b0 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
148c0 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
148d0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
148e0 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
148f0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
14900 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
14910 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
14920 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
14930 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
14940 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14950 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
14960 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
14970 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
14980 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
14990 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
149a0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
149b0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
149c0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
149d0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
149e0 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
149f0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
14a00 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
14a10 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
14a20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14a30 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
14a40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
14a50 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
14a60 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
14a70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
14a80 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
14a90 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
14aa0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
14ab0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
14ac0 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
14ad0 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
14ae0 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
14af0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
14b00 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
14b10 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
14b20 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
14b30 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
14b40 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
14b50 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
14b60 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
14b70 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
14b80 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
14b90 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14ba0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
14bb0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
14bc0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
14bd0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
14be0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
14bf0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
14c00 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
14c10 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
14c20 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
14c30 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
14c40 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
14c50 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
14c60 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
14c70 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
14c80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
14c90 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
14ca0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
14cb0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14cc0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
14cd0 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
14ce0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
14cf0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
14d00 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
14d10 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
14d20 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
14d30 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
14d40 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
14d50 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
14d60 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
14d70 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
14d80 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
14d90 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
14da0 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
14db0 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
14dc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
14dd0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
14de0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
14df0 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
14e00 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
14e10 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
14e20 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14e30 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
14e40 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
14e50 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
14e60 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
14e70 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
14e80 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
14e90 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
14ea0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
14eb0 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
14ec0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
14ed0 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
14ee0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
14ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
14f00 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
14f10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
14f20 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
14f30 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
14f40 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
14f50 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
14f60 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
14f70 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14f80 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14f90 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
14fa0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14fb0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
14fc0 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
14fd0 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
14fe0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
14ff0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
15000 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
15010 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
15020 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
15030 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
15040 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
15050 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
15060 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
15070 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15080 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
15090 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
150a0 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
150b0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
150c0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
150d0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
150e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
150f0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
15100 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
15110 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15120 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
15130 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
15140 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
15150 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
15160 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
15170 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
15180 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
15190 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
151a0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
151b0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
151c0 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
151d0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
151e0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
151f0 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
15200 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
15210 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
15220 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
15230 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
15240 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
15250 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15260 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
15270 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15280 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
15290 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
152a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
152b0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
152c0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
152d0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
152e0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
152f0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
15300 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
15310 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
15320 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
15330 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
15340 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
15350 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
15360 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
15370 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
15380 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
15390 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
153a0 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
153b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
153c0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
153d0 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
153e0 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
153f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
15400 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
15410 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
15420 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
15430 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15440 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
15450 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15460 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
15470 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
15480 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
15490 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
154a0 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
154b0 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
154c0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
154d0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
154e0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
154f0 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
15500 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
15510 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
15520 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15530 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
15540 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a  disabled, the .*
15550 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
15560 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
15570 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
15580 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
15590 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
155a0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
155b0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
155c0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
155d0 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
155e0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
155f0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
15600 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
15610 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
15620 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
15630 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15640 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
15650 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
15660 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
15670 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
15680 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
15690 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
156a0 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
156b0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
156c0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
156d0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
156e0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
156f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15700 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
15710 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15720 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
15730 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
15740 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
15750 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
15760 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
15770 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
15780 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
15790 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
157a0 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
157b0 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
157c0 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
157d0 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
157e0 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
157f0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
15800 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
15810 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
15820 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
15830 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
15840 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
15850 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
15860 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
15870 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
15880 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
15890 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
158a0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
158b0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
158c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
158d0 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
158e0 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
158f0 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
15900 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
15910 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
15920 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
15930 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
15940 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
15950 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
15960 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
15970 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
15980 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
15990 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
159a0 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
159b0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
159c0 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
159d0 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
159e0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
159f0 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
15a00 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
15a10 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
15a20 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
15a30 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
15a40 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
15a50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
15a60 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
15a70 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
15a80 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
15a90 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
15aa0 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
15ab0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15ac0 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
15ad0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
15ae0 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
15af0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
15b00 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
15b10 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
15b20 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
15b30 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
15b40 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
15b50 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
15b60 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
15b70 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
15b80 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
15b90 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
15ba0 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
15bb0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
15bc0 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
15bd0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
15be0 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
15bf0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
15c00 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
15c10 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
15c20 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
15c30 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
15c40 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
15c50 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
15c60 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
15c70 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
15c80 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
15c90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
15ca0 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
15cb0 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
15cc0 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
15cd0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
15ce0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
15cf0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
15d00 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
15d10 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
15d20 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
15d30 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
15d40 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
15d50 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
15d60 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
15d70 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
15d80 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
15d90 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
15da0 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
15db0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
15dc0 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
15dd0 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
15de0 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
15df0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
15e00 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
15e10 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
15e20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
15e30 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
15e40 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
15e50 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
15e60 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
15e70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
15e80 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
15e90 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
15ea0 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
15eb0 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
15ec0 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
15ed0 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
15ee0 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
15ef0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
15f00 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
15f10 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
15f20 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
15f30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
15f40 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
15f50 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
15f60 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
15f70 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
15f80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
15f90 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
15fa0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
15fb0 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
15fc0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
15fd0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
15fe0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
15ff0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16000 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
16010 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16020 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
16030 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16040 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
16050 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
16060 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
16070 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
16080 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
16090 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
160a0 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
160b0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
160c0 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
160d0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
160e0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
160f0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
16100 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
16110 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
16120 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
16130 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
16140 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
16150 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
16160 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
16170 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
16180 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
16190 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
161a0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
161b0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
161c0 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
161d0 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
161e0 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
161f0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
16200 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
16210 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
16220 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
16230 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
16240 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
16250 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
16260 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
16270 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
16280 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
16290 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
162a0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
162b0 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
162c0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
162d0 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
162e0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
162f0 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
16300 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
16310 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
16320 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
16330 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
16340 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
16350 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
16360 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
16370 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
16380 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
16390 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
163a0 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
163b0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
163c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
163d0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
163e0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
163f0 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
16400 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
16410 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
16420 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
16430 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
16440 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
16450 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16460 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
16470 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16480 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
16490 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
164a0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
164b0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
164c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
164d0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
164e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
164f0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
16500 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
16510 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
16520 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
16530 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
16540 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
16550 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
16560 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
16570 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
16580 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
16590 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
165a0 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
165b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
165c0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
165d0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
165e0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
165f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
16600 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
16610 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
16620 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
16630 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
16640 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
16650 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
16660 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
16670 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
16680 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
16690 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
166a0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
166b0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
166c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
166d0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
166e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
166f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16700 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
16710 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
16720 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
16730 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16740 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
16750 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16760 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
16770 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
16780 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16790 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
167a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
167b0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
167c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
167d0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
167e0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
167f0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
16800 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
16810 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
16820 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
16830 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
16840 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
16850 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
16860 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
16870 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
16880 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
16890 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
168a0 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
168b0 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
168c0 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
168d0 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
168e0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
168f0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
16900 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
16910 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
16920 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
16930 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
16940 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
16950 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
16960 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
16970 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
16980 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
16990 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
169a0 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
169b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
169c0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
169d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
169e0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
169f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
16a00 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
16a10 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
16a20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16a30 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
16a40 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16a50 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
16a60 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
16a70 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
16a80 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
16a90 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
16aa0 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
16ab0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
16ac0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
16ad0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
16ae0 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
16af0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
16b00 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
16b10 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
16b20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
16b30 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
16b40 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
16b50 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
16b60 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
16b70 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
16b80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16b90 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
16ba0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
16bb0 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
16bc0 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
16bd0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
16be0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
16bf0 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
16c00 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16c10 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
16c20 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
16c30 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
16c40 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
16c50 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
16c60 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
16c70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16c80 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
16c90 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16ca0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
16cb0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
16cc0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
16cd0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
16ce0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
16cf0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
16d00 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
16d10 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
16d20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
16d30 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
16d40 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
16d50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
16d60 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
16d70 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
16d80 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
16d90 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
16da0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
16db0 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
16dc0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16dd0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
16de0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16df0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
16e00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
16e10 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
16e20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
16e30 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
16e40 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
16e50 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
16e60 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
16e70 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
16e80 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
16e90 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
16ea0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
16eb0 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
16ec0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16ed0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
16ee0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16ef0 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
16f00 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
16f10 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
16f20 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
16f30 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
16f40 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
16f50 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
16f60 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
16f70 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
16f80 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
16f90 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
16fa0 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
16fb0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
16fc0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
16fd0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
16fe0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
16ff0 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
17000 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
17010 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
17020 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
17030 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
17040 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
17050 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
17060 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
17070 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
17080 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
17090 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
170a0 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
170b0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
170c0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
170d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
170e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
170f0 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
17100 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
17110 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
17120 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
17130 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
17140 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
17150 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
17160 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
17170 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
17180 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
17190 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
171a0 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
171b0 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
171c0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
171d0 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
171e0 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
171f0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
17200 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
17210 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
17220 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
17230 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
17240 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
17250 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
17260 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
17270 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
17280 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
17290 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
172a0 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
172b0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
172c0 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
172d0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
172e0 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
172f0 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
17300 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
17310 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
17320 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
17330 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
17340 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
17350 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
17360 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  RI]] <dt>SQLITE_
17370 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64  CONFIG_URI.** <d
17380 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  d> This option t
17390 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
173a0 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
173b0 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  nt. If non-zero,
173c0 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e   then.** URI han
173d0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
173e0 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
173f0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
17400 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
17410 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f  ndling.** is glo
17420 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20  bally disabled. 
17430 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
17440 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
17450 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d  led, all filenam
17460 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20  es.** passed to 
17470 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
17480 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
17490 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
174a0 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  open16()] or.** 
174b0 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
174c0 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f  t of [ATTACH] co
174d0 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72  mmands are inter
174e0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20  preted as URIs, 
174f0 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
17500 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
17510 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
17520 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65  _URI] flag is se
17530 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  t when the datab
17540 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
17550 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20  n is opened. If 
17560 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
17570 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
17580 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
17590 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
175a0 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
175b0 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
175c0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
175d0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
175e0 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
175f0 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49   By default, URI
17600 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
17610 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
17620 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
17630 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
17640 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
17650 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
17660 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
17670 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  mbol defined..**
17680 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17690 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
176a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
176b0 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
176c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
176d0 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
176e0 43 4f 4e 46 4e 49 47 5f 47 45 54 50 43 41 43 48  CONFNIG_GETPCACH
176f0 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20  E.** <dd> These 
17700 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f  options are obso
17710 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20  lete and should 
17720 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e  not be used by n
17730 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79  ew code..** They
17740 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
17750 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
17760 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72  atibility but ar
17770 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  e now no-ops..**
17780 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
17790 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
177a0 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
177b0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
177c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
177d0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
177e0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
177f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17800 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
17810 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
17820 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17830 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
17840 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
17850 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
17860 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17870 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
17880 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
17890 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
178a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
178b0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
178c0 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
178d0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
178e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
178f0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
17900 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
17910 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
17920 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
17930 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
17940 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
17950 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
17960 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
17970 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17980 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
17990 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
179a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
179b0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
179c0 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
179d0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
179e0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
179f0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
17a00 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
17a10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
17a20 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
17a30 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
17a40 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
17a50 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
17a60 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
17a70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17a80 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
17a90 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
17aa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17ab0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
17ac0 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
17ad0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17ae0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
17af0 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
17b00 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
17b10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
17b20 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
17b30 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
17b40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17b50 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
17b60 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
17b70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17b80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
17b90 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
17ba0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
17bb0 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
17bc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
17bd0 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
17be0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
17bf0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 0a 2f  _methods2* */../
17c00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
17c10 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
17c20 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
17c30 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
17c40 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
17c50 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
17c60 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
17c70 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
17c80 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
17c90 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
17ca0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
17cb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
17cc0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
17cd0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
17ce0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17cf0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
17d00 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
17d10 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
17d20 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
17d30 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
17d40 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
17d50 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
17d60 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
17d70 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
17d80 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
17d90 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
17da0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
17db0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
17dc0 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
17dd0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
17de0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
17df0 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
17e00 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
17e10 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
17e20 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
17e30 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
17e40 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
17e50 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
17e60 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
17e70 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
17e80 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
17e90 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
17ea0 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
17eb0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
17ec0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
17ed0 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
17ee0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
17ef0 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
17f00 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
17f10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
17f20 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
17f30 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
17f40 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
17f50 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17f60 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
17f70 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
17f80 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
17f90 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
17fa0 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
17fb0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
17fc0 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
17fd0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17fe0 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
17ff0 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
18000 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
18010 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
18020 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
18030 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
18040 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
18050 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
18060 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
18070 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
18080 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
18090 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
180a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
180b0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
180c0 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
180d0 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
180e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
180f0 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
18100 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
18110 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
18120 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
18130 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
18140 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
18150 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
18160 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
18170 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
18180 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
18190 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
181a0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
181b0 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
181c0 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
181d0 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
181e0 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
181f0 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
18200 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
18210 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
18220 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
18230 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
18240 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18250 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
18260 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
18270 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
18280 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
18290 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
182a0 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
182b0 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
182c0 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
182d0 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
182e0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
182f0 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
18300 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
18310 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
18320 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
18330 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
18340 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
18350 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
18360 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
18370 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
18380 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
18390 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
183a0 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
183b0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
183c0 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
183d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
183e0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
183f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
18400 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18410 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18420 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
18430 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
18440 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
18450 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
18460 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
18470 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
18480 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
18490 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
184a0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
184b0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
184c0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
184d0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
184e0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
184f0 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
18500 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
18510 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
18520 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
18530 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
18540 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
18550 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
18560 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
18570 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
18580 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
18590 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
185a0 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
185b0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
185c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
185d0 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
185e0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
185f0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18600 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
18610 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18620 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
18630 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18640 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18650 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
18660 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
18670 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
18680 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
18690 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
186a0 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
186b0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
186c0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
186d0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
186e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
186f0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
18700 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
18710 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
18720 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
18730 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
18740 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
18750 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
18760 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
18770 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18780 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
18790 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
187a0 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
187b0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
187c0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
187d0 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
187e0 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
187f0 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
18800 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
18810 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18820 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
18830 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
18840 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
18850 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
18860 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
18870 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
18880 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
18890 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
188a0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
188b0 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
188c0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
188d0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
188e0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
188f0 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20     1002  /* int 
18900 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18910 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18920 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
18930 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1003  /* int int
18940 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  * */.../*.** CAP
18950 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
18960 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
18970 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
18980 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18990 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
189a0 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
189b0 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
189c0 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
189d0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
189e0 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
189f0 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
18a00 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
18a10 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
18a20 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
18a30 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
18a40 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53  patibility..*/.S
18a50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
18a60 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
18a70 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
18a80 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
18a90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18aa0 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
18ab0 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  owid.**.** ^Each
18ac0 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
18ad0 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
18ae0 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
18af0 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
18b00 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
18b10 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
18b20 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
18b30 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
18b40 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
18b50 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
18b60 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
18b70 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
18b80 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
18b90 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
18ba0 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
18bb0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
18bc0 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
18bd0 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
18be0 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
18bf0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
18c00 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
18c10 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
18c20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
18c30 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  wid..**.** ^This
18c40 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
18c50 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
18c60 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
18c70 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
18c80 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
18c90 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
18ca0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
18cb0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
18cc0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18cd0 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65  .  ^As of SQLite
18ce0 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
18cf0 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  this routines.**
18d00 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73   records the las
18d10 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f  t insert rowid o
18d20 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20  f both ordinary 
18d30 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74  tables and [virt
18d40 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20  ual tables]..** 
18d50 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
18d60 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
18d70 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
18d80 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
18d90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
18da0 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
18db0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
18dc0 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
18dd0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
18de0 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
18df0 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
18e00 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
18e10 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
18e20 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
18e30 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
18e40 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
18e50 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
18e60 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
18e70 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
18e80 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
18e90 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
18ea0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
18eb0 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
18ec0 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
18ed0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
18ee0 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
18ef0 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
18f00 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
18f10 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
18f20 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
18f30 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
18f40 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
18f50 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
18f60 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
18f70 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
18f80 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
18f90 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
18fa0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18fb0 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
18fc0 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
18fd0 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
18fe0 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
18ff0 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
19000 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
19010 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
19020 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
19030 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
19040 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
19050 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
19060 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
19070 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
19080 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
19090 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
190a0 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
190b0 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
190c0 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
190d0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
190e0 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
190f0 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
19100 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
19110 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
19120 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
19130 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
19140 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
19150 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
19160 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
19170 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
19180 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
19190 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
191a0 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
191b0 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
191c0 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
191d0 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
191e0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
191f0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
19200 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
19210 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
19220 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
19230 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19240 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
19250 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
19260 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
19270 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
19280 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
19290 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
192a0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
192b0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
192c0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
192d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
192e0 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
192f0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
19300 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
19310 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
19320 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
19330 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
19340 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
19350 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
19360 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
19370 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
19380 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
19390 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
193a0 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  owid]..*/.SQLITE
193b0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
193c0 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
193d0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
193e0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
193f0 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
19400 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
19410 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
19420 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
19430 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
19440 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
19450 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68  ows that were ch
19460 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65  anged.** or inse
19470 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20  rted or deleted 
19480 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
19490 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53  ntly completed S
194a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
194b0 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
194c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
194d0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
194e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
194f0 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73  * ^(Only changes
19500 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
19510 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
19520 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  the [INSERT], [U
19530 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44  PDATE],.** or [D
19540 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
19550 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41   are counted.  A
19560 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
19570 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72   caused by.** tr
19580 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69  iggers or [forei
19590 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
195a0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
195b0 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73  )^ Use the.** [s
195c0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
195d0 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
195e0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74   to find the tot
195f0 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  al number of cha
19600 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e  nges.** includin
19610 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
19620 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64   by triggers and
19630 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74   foreign key act
19640 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61  ions..**.** ^Cha
19650 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
19660 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65  hat are simulate
19670 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44  d by an [INSTEAD
19680 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20   OF trigger].** 
19690 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
196a0 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c    Only real tabl
196b0 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
196c0 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  unted..**.** ^(A
196d0 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
196e0 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
196f0 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
19700 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
19710 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
19720 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
19730 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
19740 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
19750 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
19760 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52  de effects of [R
19770 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
19780 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a  nt resolution,.*
19790 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52  * rollback, ABOR
197a0 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44  T processing, [D
197b0 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62  ROP TABLE], or b
197c0 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d  y any other.** m
197d0 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74  echanisms do not
197e0 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74   count as direct
197f0 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a   row changes.)^.
19800 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
19810 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
19820 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
19830 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
19840 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
19850 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b  he script of a [
19860 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
19870 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d   trigger]. .** M
19880 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
19890 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
198a0 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
198b0 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
198c0 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
198d0 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
198e0 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
198f0 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
19900 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
19910 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
19920 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
19930 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
19940 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
19950 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
19960 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
19970 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
19980 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
19990 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
199a0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
199b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
199c0 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
199d0 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
199e0 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
199f0 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
19a00 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
19a10 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
19a20 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f  ber of direct ro
19a30 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  w changes in the
19a40 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
19a50 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
19a60 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
19a70 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
19a80 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  ame.** trigger c
19a90 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
19aa0 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64  hus, when called
19ab0 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
19ac0 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69  vel, this functi
19ad0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
19ae0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  * number of chan
19af0 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
19b00 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
19b10 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
19b20 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63  .** that also oc
19b30 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f  curred at the to
19b40 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68  p level.  ^(With
19b50 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
19b60 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
19b70 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
19b80 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
19b90 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
19ba0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
19bb0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
19bc0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
19bd0 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
19be0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
19bf0 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
19c00 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
19c10 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
19c20 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
19c30 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
19c40 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
19c50 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
19c60 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
19c70 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
19c80 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
19c90 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a  own context.)^.*
19ca0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
19cb0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
19cc0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
19cd0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
19ce0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
19cf0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
19d00 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
19d10 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
19d20 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
19d30 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
19d40 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
19d50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19d60 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
19d70 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
19d80 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
19d90 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19da0 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
19db0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
19dc0 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  ningful..*/.SQLI
19dd0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
19de0 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
19df0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
19e00 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
19e10 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
19e20 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
19e30 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
19e40 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
19e50 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
19e60 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a  ed by [INSERT],.
19e70 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ** [UPDATE] or [
19e80 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
19e90 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
19ea0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19eb0 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
19ec0 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65  * ^(The count re
19ed0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
19ee0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
19ef0 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  ) includes all c
19f00 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61  hanges.** from a
19f10 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  ll [CREATE TRIGG
19f20 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f  ER | trigger] co
19f30 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67  ntexts and chang
19f40 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66  es made by.** [f
19f50 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
19f60 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ns]. However,.**
19f70 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
19f80 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
19f90 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
19fa0 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
19fb0 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
19fc0 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
19fd0 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
19fe0 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
19ff0 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
1a000 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
1a010 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
1a020 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
1a030 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
1a040 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
1a050 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
1a060 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1a070 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
1a080 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
1a090 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
1a0a0 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20  e counted.)^.** 
1a0b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74  ^The sqlite3_tot
1a0c0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  al_changes() fun
1a0d0 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65  ction counts the
1a0e0 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e   changes as soon
1a0f0 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   as.** the state
1a100 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
1a110 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
1a120 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
1a130 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20  ement handle.** 
1a140 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
1a150 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
1a160 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
1a170 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
1a180 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1a190 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1a1a0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1a1b0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1a1c0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1a1d0 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
1a1e0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1a1f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1a200 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1a210 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1a220 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1a230 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1a240 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
1a250 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
1a260 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1a270 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
1a280 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
1a290 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1a2a0 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  ningful..*/.SQLI
1a2b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1a2c0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1a2d0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1a2e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
1a2f0 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
1a300 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
1a310 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1a320 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
1a330 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
1a340 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
1a350 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
1a360 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
1a370 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
1a380 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
1a390 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
1a3a0 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
1a3b0 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
1a3c0 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
1a3d0 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
1a3e0 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
1a3f0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
1a400 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
1a410 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
1a420 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
1a430 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
1a440 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
1a450 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
1a460 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
1a470 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
1a480 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1a490 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
1a4a0 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
1a4b0 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
1a4c0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1a4d0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
1a4e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a4f0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
1a500 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
1a510 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
1a520 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1a530 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1a540 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
1a550 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
1a560 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
1a570 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
1a580 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a590 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
1a5a0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
1a5b0 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
1a5c0 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
1a5d0 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
1a5e0 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
1a5f0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
1a600 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
1a610 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
1a620 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
1a630 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
1a640 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
1a650 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
1a660 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1a670 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1a680 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1a690 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
1a6a0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
1a6b0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
1a6c0 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
1a6d0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
1a6e0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
1a6f0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
1a700 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
1a710 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
1a720 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
1a730 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
1a740 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1a750 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
1a760 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a770 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
1a780 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
1a790 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1a7a0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1a7b0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1a7c0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
1a7d0 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
1a7e0 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
1a7f0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
1a800 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
1a810 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
1a820 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
1a830 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
1a840 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a850 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
1a860 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1a870 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1a880 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
1a890 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
1a8a0 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
1a8b0 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
1a8c0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1a8d0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
1a8e0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
1a8f0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a900 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
1a910 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
1a920 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1a930 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
1a940 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
1a950 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
1a960 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1a970 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1a980 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1a990 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1a9a0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1a9b0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1a9c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
1a9d0 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
1a9e0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
1a9f0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1aa00 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
1aa10 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
1aa20 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1aa30 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
1aa40 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
1aa50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1aa60 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1aa70 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
1aa80 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
1aa90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1aaa0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
1aab0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
1aac0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
1aad0 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
1aae0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
1aaf0 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
1ab00 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1ab10 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
1ab20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
1ab30 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
1ab40 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
1ab50 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
1ab60 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
1ab70 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
1ab80 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
1ab90 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
1aba0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
1abb0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1abc0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
1abd0 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
1abe0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
1abf0 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
1ac00 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
1ac10 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
1ac20 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
1ac30 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
1ac40 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
1ac50 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
1ac60 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
1ac70 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
1ac80 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
1ac90 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
1aca0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
1acb0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
1acc0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
1acd0 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
1ace0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
1acf0 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
1ad00 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
1ad10 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
1ad20 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
1ad30 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
1ad40 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
1ad50 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
1ad60 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
1ad70 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
1ad80 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
1ad90 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1ada0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
1adb0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1adc0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
1add0 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
1ade0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
1adf0 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
1ae00 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1ae10 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1ae20 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
1ae30 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1ae40 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
1ae50 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
1ae60 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
1ae70 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
1ae80 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
1ae90 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
1aea0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
1aeb0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
1aec0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
1aed0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
1aee0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
1aef0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
1af00 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
1af10 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1af20 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
1af30 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
1af40 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
1af50 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
1af60 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
1af70 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
1af80 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
1af90 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
1afa0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1afb0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1afc0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
1afd0 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
1afe0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1aff0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1b000 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1b010 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1b020 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
1b030 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1b040 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1b050 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1b060 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1b070 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1b080 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1b090 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49  e order..*/.SQLI
1b0a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1b0b0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
1b0c0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51  t char *sql);.SQ
1b0d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1b0e0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b0f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
1b100 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b110 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
1b120 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
1b130 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
1b140 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
1b150 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
1b160 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1b170 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
1b180 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
1b190 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
1b1a0 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
1b1b0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
1b1c0 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
1b1d0 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
1b1e0 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
1b1f0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
1b200 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1b210 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
1b220 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
1b230 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
1b240 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
1b250 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
1b260 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
1b270 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
1b280 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
1b290 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1b2a0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
1b2b0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1b2c0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
1b2d0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
1b2e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1b2f0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1b300 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
1b310 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
1b320 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
1b330 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1b340 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
1b350 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
1b360 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1b370 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
1b380 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1b390 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1b3a0 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
1b3b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
1b3c0 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
1b3d0 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
1b3e0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
1b3f0 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
1b400 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
1b410 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
1b420 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
1b430 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
1b440 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1b450 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
1b460 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
1b470 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
1b480 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
1b490 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1b4a0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1b4b0 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
1b4c0 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
1b4d0 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
1b4e0 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
1b4f0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
1b500 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
1b510 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
1b520 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
1b530 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
1b540 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
1b550 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
1b560 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
1b570 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
1b580 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
1b590 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
1b5a0 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
1b5b0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
1b5c0 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
1b5d0 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
1b5e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
1b5f0 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
1b600 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
1b610 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
1b620 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
1b630 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
1b640 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
1b650 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
1b660 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1b670 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
1b680 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
1b690 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
1b6a0 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
1b6b0 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
1b6c0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1b6d0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
1b6e0 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
1b6f0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
1b700 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
1b710 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
1b720 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
1b730 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
1b740 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1b750 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
1b760 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1b770 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
1b780 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
1b790 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1b7a0 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
1b7b0 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
1b7c0 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
1b7d0 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
1b7e0 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
1b7f0 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
1b800 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
1b810 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1b820 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
1b830 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
1b840 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
1b850 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
1b860 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
1b870 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
1b880 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
1b890 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
1b8a0 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
1b8b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
1b8c0 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
1b8d0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
1b8e0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
1b8f0 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
1b900 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
1b910 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
1b920 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
1b930 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
1b940 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
1b950 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
1b960 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
1b970 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
1b980 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
1b990 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
1b9a0 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
1b9b0 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
1b9c0 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
1b9d0 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
1b9e0 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
1b9f0 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
1ba00 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
1ba10 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
1ba20 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
1ba30 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
1ba40 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
1ba50 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
1ba60 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
1ba70 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
1ba80 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
1ba90 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
1baa0 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
1bab0 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
1bac0 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
1bad0 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
1bae0 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
1baf0 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
1bb00 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
1bb10 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
1bb20 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
1bb30 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
1bb40 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
1bb50 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
1bb60 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
1bb70 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
1bb80 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
1bb90 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
1bba0 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
1bbb0 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
1bbc0 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
1bbd0 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
1bbe0 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
1bbf0 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
1bc00 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
1bc10 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
1bc20 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
1bc30 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
1bc40 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
1bc50 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1bc60 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1bc70 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
1bc80 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
1bc90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
1bca0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
1bcb0 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
1bcc0 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
1bcd0 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
1bce0 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
1bcf0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
1bd00 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
1bd10 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
1bd20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
1bd30 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
1bd40 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
1bd50 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
1bd60 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
1bd70 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
1bd80 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1bd90 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1bda0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1bdb0 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
1bdc0 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1bdd0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1bde0 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1bdf0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1be00 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1be10 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1be20 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1be30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1be40 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1be50 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1be60 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1be70 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
1be80 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1be90 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
1bea0 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
1beb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1bec0 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
1bed0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1bee0 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
1bef0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1bf00 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
1bf10 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
1bf20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
1bf30 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
1bf40 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
1bf50 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
1bf60 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
1bf70 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
1bf80 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
1bf90 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1bfa0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
1bfb0 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
1bfc0 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
1bfd0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1bfe0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1bff0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
1c000 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
1c010 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
1c020 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
1c030 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
1c040 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
1c050 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
1c060 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1c070 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
1c080 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
1c090 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
1c0a0 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
1c0b0 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
1c0c0 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
1c0d0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1c0e0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1c0f0 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
1c100 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1c110 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c120 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
1c130 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1c140 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1c150 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1c160 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1c170 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1c180 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1c190 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1c1a0 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1c1b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1c1c0 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51  cleared.)^.*/.SQ
1c1d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1c1e0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1c1f0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1c200 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
1c210 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
1c220 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
1c230 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
1c240 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1c250 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1c260 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1c270 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1c280 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1c290 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1c2a0 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1c2b0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1c2c0 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1c2d0 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1c2e0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1c2f0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1c300 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1c310 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c320 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1c330 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1c340 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1c350 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1c360 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1c370 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1c380 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1c390 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1c3a0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1c3b0 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1c3c0 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1c3d0 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1c3e0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1c3f0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1c400 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1c410 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1c420 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1c430 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1c440 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1c450 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1c460 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1c470 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1c480 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1c490 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1c4a0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1c4b0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1c4c0 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1c4d0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1c4e0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1c4f0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1c500 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1c510 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1c520 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1c530 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1c540 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1c550 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1c560 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1c570 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1c580 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1c590 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1c5a0 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1c5b0 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1c5c0 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1c5d0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1c5e0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1c5f0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1c600 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1c610 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1c620 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1c630 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1c640 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1c650 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1c660 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1c670 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1c680 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1c690 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1c6a0 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1c6b0 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1c6c0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1c6d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1c6e0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1c6f0 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1c700 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1c710 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1c720 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1c730 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1c740 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1c750 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c760 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1c770 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1c780 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1c790 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1c7a0 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1c7b0 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1c7c0 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1c7d0 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1c7e0 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1c7f0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c800 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1c810 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1c820 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1c830 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1c840 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1c850 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1c860 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1c870 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1c880 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1c890 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1c8a0 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1c8b0 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1c8c0 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1c8d0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1c8e0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1c8f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1c900 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1c910 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1c920 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1c930 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1c940 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1c950 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1c960 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1c970 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1c980 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1c990 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1c9a0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1c9b0 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1c9c0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1c9d0 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1c9e0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1c9f0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1ca00 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1ca10 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1ca20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1ca30 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1ca40 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1ca50 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1ca60 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1ca70 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1ca80 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1ca90 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1caa0 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1cab0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1cac0 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1cad0 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1cae0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1caf0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1cb00 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1cb10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1cb20 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1cb30 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1cb40 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1cb50 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1cb60 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1cb70 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1cb80 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1cb90 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1cba0 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1cbb0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1cbc0 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1cbd0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1cbe0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1cbf0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1cc00 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1cc10 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1cc20 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1cc30 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1cc40 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1cc50 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1cc60 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1cc70 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1cc80 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1cc90 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1cca0 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1ccb0 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1ccc0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1ccd0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1cce0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1ccf0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1cd00 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1cd10 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1cd20 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1cd30 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1cd40 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1cd50 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1cd60 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1cd70 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1cd80 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1cd90 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1cda0 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1cdb0 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1cdc0 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1cdd0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1cde0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1cdf0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1ce00 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1ce10 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1ce20 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1ce30 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1ce40 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1ce50 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1ce60 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1ce70 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1ce80 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  PI int sqlite3_g
1ce90 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
1cea0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1ceb0 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
1cec0 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
1ced0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1cee0 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
1cef0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
1cf00 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
1cf10 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
1cf20 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
1cf30 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
1cf40 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1cf50 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
1cf60 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1cf70 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
1cf80 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1cf90 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
1cfa0 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
1cfb0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1cfc0 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
1cfd0 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
1cfe0 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  here */.);.SQLIT
1cff0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1d000 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1d010 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1d020 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1d030 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1d040 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1d050 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1d060 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1d070 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1d080 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1d090 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1d0a0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1d0b0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1d0c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1d0d0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1d0e0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1d0f0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1d100 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1d110 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1d120 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1d130 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1d140 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1d150 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1d160 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1d170 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1d180 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1d190 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1d1a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1d1b0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1d1c0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1d1d0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1d1e0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1d1f0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1d200 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1d210 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1d220 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1d230 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1d240 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1d250 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1d260 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1d270 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1d280 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1d290 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1d2a0 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1d2b0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1d2c0 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1d2d0 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1d2e0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1d2f0 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1d300 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1d310 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1d320 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1d330 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1d340 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1d350 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1d360 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1d370 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1d380 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1d390 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1d3a0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1d3b0 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1d3c0 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1d3d0 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1d3e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1d3f0 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1d400 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1d410 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1d420 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1d430 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1d440 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1d450 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1d460 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1d470 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1d480 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1d490 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1d4a0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1d4b0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1d4c0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1d4d0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1d4e0 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1d4f0 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1d500 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1d510 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1d520 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1d530 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1d540 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1d550 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1d560 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1d570 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1d580 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1d590 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1d5a0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1d5b0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1d5c0 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1d5d0 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1d5e0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1d5f0 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1d600 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1d610 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1d620 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1d630 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1d640 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d650 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1d660 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1d670 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1d680 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1d690 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1d6a0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1d6b0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1d6c0 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1d6d0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1d6e0 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1d6f0 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1d700 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1d710 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1d720 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1d730 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1d740 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1d750 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1d760 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
1d770 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
1d780 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
1d790 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1d7a0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
1d7b0 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
1d7c0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
1d7d0 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
1d7e0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
1d7f0 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
1d800 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
1d810 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
1d820 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
1d830 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
1d840 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
1d850 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
1d860 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
1d870 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
1d880 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
1d890 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
1d8a0 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
1d8b0 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
1d8c0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1d8d0 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
1d8e0 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
1d8f0 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
1d900 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1d910 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1d920 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
1d930 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
1d940 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
1d950 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1d960 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
1d970 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
1d980 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1d990 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1d9a0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1d9b0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1d9c0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1d9d0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1d9e0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1d9f0 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1da00 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1da10 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1da20 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1da30 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1da40 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1da50 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1da60 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1da70 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1da80 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1da90 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1daa0 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1dab0 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1dac0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1dad0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1dae0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1daf0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1db00 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1db10 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1db20 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1db30 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1db40 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1db50 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1db60 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1db70 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1db80 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1db90 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1dba0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1dbb0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1dbc0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1dbd0 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1dbe0 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1dbf0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1dc00 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1dc10 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1dc20 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1dc30 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1dc40 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1dc50 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1dc60 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1dc70 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1dc80 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1dc90 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1dca0 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1dcb0 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1dcc0 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1dcd0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1dce0 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1dcf0 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1dd00 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1dd10 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1dd20 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1dd30 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1dd40 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1dd50 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1dd60 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1dd70 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1dd80 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1dd90 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1dda0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1ddb0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1ddc0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1ddd0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1dde0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1ddf0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1de00 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1de10 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1de20 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1de30 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1de40 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1de50 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1de60 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1de70 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1de80 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1de90 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1dea0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1deb0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1dec0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1ded0 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1dee0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1def0 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1df00 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1df10 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1df20 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1df30 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1df40 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1df50 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1df60 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1df70 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1df80 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1df90 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1dfa0 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  ing.)^.*/.SQLITE
1dfb0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1dfc0 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1dfd0 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c   char*,...);.SQL
1dfe0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1dff0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
1e000 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1e010 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ist);.SQLITE_API
1e020 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1e030 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1e040 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1e050 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1e060 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1e070 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1e080 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1e090 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1e0a0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1e0b0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1e0c0 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1e0d0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1e0e0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1e0f0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1e100 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1e110 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1e120 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1e130 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1e140 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1e150 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1e160 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1e170 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1e180 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1e190 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1e1a0 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1e1b0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1e1c0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1e1d0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1e1e0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1e1f0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1e200 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1e210 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1e220 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1e230 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1e240 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1e250 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1e260 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1e270 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1e280 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1e290 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1e2a0 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1e2b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1e2c0 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1e2d0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1e2e0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1e2f0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1e300 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1e310 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1e320 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1e330 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1e340 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1e350 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1e360 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1e370 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1e380 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1e390 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1e3a0 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1e3b0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1e3c0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1e3d0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1e3e0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1e3f0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1e400 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1e410 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1e420 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1e430 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1e440 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1e450 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1e460 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1e470 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1e480 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1e490 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1e4a0 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1e4b0 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1e4c0 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1e4d0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1e4e0 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1e4f0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1e500 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1e510 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1e520 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1e530 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1e540 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1e550 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1e560 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1e570 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1e580 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1e590 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1e5a0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1e5b0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1e5c0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1e5d0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
1e5e0 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
1e5f0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1e600 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1e610 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1e620 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
1e630 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
1e640 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
1e650 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
1e660 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
1e670 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
1e680 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
1e690 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
1e6a0 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
1e6b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1e6c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1e6d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1e6e0 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1e6f0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1e700 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1e710 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1e720 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
1e730 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1e740 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1e750 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
1e760 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1e770 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1e780 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
1e790 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1e7a0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1e7b0 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1e7c0 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1e7d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1e7e0 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
1e7f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1e800 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1e810 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
1e820 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1e830 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1e840 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
1e850 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
1e860 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1e870 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
1e880 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
1e890 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
1e8a0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
1e8b0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
1e8c0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1e8d0 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
1e8e0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
1e8f0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1e900 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1e910 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1e920 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
1e930 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1e940 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
1e950 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1e960 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1e970 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1e980 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
1e990 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
1e9a0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
1e9b0 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1e9c0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1e9d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1e9e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
1e9f0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1ea00 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
1ea10 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1ea20 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1ea30 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1ea40 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1ea50 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1ea60 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1ea70 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1ea80 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1ea90 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1eaa0 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1eab0 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1eac0 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1ead0 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1eae0 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1eaf0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1eb00 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1eb10 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1eb20 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1eb30 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1eb40 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1eb50 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1eb60 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1eb70 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1eb80 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1eb90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1eba0 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1ebb0 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f  ** The Windows O
1ebc0 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1ebd0 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
1ebe0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
1ebf0 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
1ec00 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
1ec10 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
1ec20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
1ec30 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
1ec40 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
1ec50 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
1ec60 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
1ec70 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
1ec80 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
1ec90 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
1eca0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
1ecb0 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
1ecc0 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
1ecd0 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
1ece0 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
1ecf0 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
1ed00 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
1ed10 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
1ed20 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
1ed30 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
1ed40 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
1ed50 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
1ed60 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ed70 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
1ed80 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
1ed90 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
1eda0 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
1edb0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
1edc0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1edd0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
1ede0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
1edf0 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
1ee00 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
1ee10 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
1ee20 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
1ee30 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
1ee40 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
1ee50 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
1ee60 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
1ee70 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
1ee80 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
1ee90 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1eea0 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51  ealloc()]..*/.SQ
1eeb0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
1eec0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
1eed0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
1eee0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1eef0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1ef00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1ef10 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
1ef20 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1ef30 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1ef40 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
1ef50 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
1ef60 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
1ef70 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
1ef80 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
1ef90 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
1efa0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
1efb0 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
1efc0 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
1efd0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1efe0 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
1eff0 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
1f000 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1f010 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
1f020 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
1f030 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1f040 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
1f050 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1f060 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
1f070 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
1f080 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
1f090 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
1f0a0 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
1f0b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1f0c0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
1f0d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1f0e0 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
1f0f0 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
1f100 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
1f110 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
1f120 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
1f130 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
1f140 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1f150 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1f160 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
1f170 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1f180 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1f190 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
1f1a0 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
1f1b0 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
1f1c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1f1d0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1f1e0 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
1f1f0 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
1f200 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
1f210 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
1f220 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
1f230 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
1f240 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
1f250 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1f260 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
1f270 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
1f280 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1f290 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
1f2a0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1f2b0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
1f2c0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
1f2d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1f2e0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1f2f0 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
1f300 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1f310 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1f320 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
1f330 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
1f340 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
1f350 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
1f360 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
1f370 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1f380 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1f390 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
1f3a0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
1f3b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1f3c0 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1f3d0 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1f3e0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1f3f0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1f400 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1f410 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
1f420 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
1f430 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
1f440 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
1f450 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
1f460 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
1f470 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
1f480 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
1f490 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
1f4a0 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
1f4b0 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
1f4c0 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
1f4d0 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
1f4e0 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
1f4f0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
1f500 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
1f510 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
1f520 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
1f530 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1f540 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
1f550 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
1f560 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
1f570 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
1f580 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
1f590 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
1f5a0 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
1f5b0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
1f5c0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
1f5d0 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
1f5e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
1f5f0 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20  invoked (either 
1f600 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79  internally or by
1f610 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
1f620 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73  ion) the PRNG is
1f630 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
1f640 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
1f650 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52  d.** from the xR
1f660 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
1f670 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
1f680 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1f690 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c  ject..** ^On all
1f6a0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
1f6b0 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65  cations, the pse
1f6c0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1f6d0 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1f6e0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1f6f0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1f700 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1f710 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1f720 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51  ** method..*/.SQ
1f730 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1f740 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
1f750 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
1f760 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f770 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
1f780 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
1f790 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1f7a0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
1f7b0 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
1f7c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
1f7d0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
1f7e0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1f7f0 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
1f800 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
1f810 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
1f820 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f830 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1f840 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
1f850 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
1f860 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
1f870 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1f880 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
1f890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f8a0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
1f8b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1f8c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
1f8d0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
1f8e0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
1f8f0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
1f900 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
1f910 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
1f920 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
1f930 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
1f940 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
1f950 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1f960 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1f970 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
1f980 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
1f990 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
1f9a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1f9b0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
1f9c0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1f9d0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
1f9e0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
1f9f0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
1fa00 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
1fa10 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
1fa20 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
1fa30 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
1fa40 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
1fa50 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
1fa60 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
1fa70 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
1fa80 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
1fa90 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
1faa0 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
1fab0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fac0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
1fad0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
1fae0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
1faf0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
1fb00 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1fb10 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
1fb20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fb30 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1fb40 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1fb50 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
1fb60 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1fb70 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1fb80 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
1fb90 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
1fba0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1fbb0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
1fbc0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
1fbd0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
1fbe0 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
1fbf0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1fc00 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
1fc10 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1fc20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1fc30 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1fc40 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
1fc50 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1fc60 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1fc70 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1fc80 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
1fc90 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
1fca0 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
1fcb0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1fcc0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1fcd0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1fce0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
1fcf0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
1fd00 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1fd10 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1fd20 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
1fd30 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1fd40 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
1fd50 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1fd60 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
1fd70 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
1fd80 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1fd90 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
1fda0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1fdb0 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
1fdc0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
1fdd0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
1fde0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1fdf0 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
1fe00 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1fe10 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
1fe20 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
1fe30 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
1fe40 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1fe50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1fe60 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1fe70 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
1fe80 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1fe90 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1fea0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1feb0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
1fec0 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
1fed0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
1fee0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
1fef0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
1ff00 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
1ff10 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
1ff20 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
1ff30 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
1ff40 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
1ff50 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
1ff60 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
1ff70 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
1ff80 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
1ff90 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
1ffa0 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
1ffb0 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
1ffc0 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
1ffd0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1ffe0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1fff0 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
20000 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20010 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
20020 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
20030 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
20040 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
20050 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
20060 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
20070 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
20080 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
20090 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
200a0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
200b0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
200c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
200d0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
200e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
200f0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
20100 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
20110 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
20120 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
20130 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
20140 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
20150 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
20160 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
20170 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
20180 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
20190 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
201a0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
201b0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
201c0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
201d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
201e0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
201f0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
20200 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
20210 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
20220 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
20230 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
20240 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
20250 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
20260 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
20270 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
20280 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
20290 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
202a0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
202b0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
202c0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
202d0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
202e0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
202f0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
20300 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
20310 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
20320 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
20330 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
20340 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
20350 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
20360 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
20370 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
20380 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
20390 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
203a0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
203b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
203c0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
203d0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
203e0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
203f0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
20400 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
20410 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
20420 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
20430 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
20440 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
20450 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
20460 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
20470 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
20480 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
20490 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
204a0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
204b0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
204c0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
204d0 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
204e0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
204f0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
20500 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
20510 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
20520 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
20530 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
20540 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
20550 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
20560 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
20570 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
20580 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20590 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
205a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
205b0 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
205c0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
205d0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
205e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
205f0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
20600 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
20610 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
20620 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
20630 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
20640 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
20650 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
20660 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
20670 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
20680 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
20690 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
206a0 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
206b0 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
206c0 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
206d0 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
206e0 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
206f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
20700 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
20710 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
20720 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20730 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
20740 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
20750 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
20760 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
20770 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
20780 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
20790 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
207a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
207b0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
207c0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
207d0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
207e0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
207f0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
20800 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
20810 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
20820 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
20830 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
20840 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
20850 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
20860 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
20870 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
20880 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
20890 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
208a0 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51  ma change..*/.SQ
208b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
208c0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
208d0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
208e0 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
208f0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
20900 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
20910 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
20920 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
20930 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
20940 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20950 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
20960 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
20970 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
20980 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
20990 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
209a0 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
209b0 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
209c0 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
209d0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
209e0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
209f0 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
20a00 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
20a10 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
20a20 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
20a30 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
20a40 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20a50 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
20a60 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
20a70 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
20a80 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
20a90 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
20aa0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
20ab0 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
20ac0 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
20ad0 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a   | return code].
20ae0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ** from the [sql
20af0 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
20b00 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
20b10 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
20b20 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
20b30 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
20b40 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
20b50 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
20b60 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
20b70 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
20b80 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
20b90 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
20ba0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
20bb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
20bc0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
20bd0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
20be0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
20bf0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
20c00 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
20c10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20c20 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
20c30 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
20c40 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
20c50 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
20c60 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
20c70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20c80 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
20c90 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
20ca0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
20cb0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
20cc0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
20cd0 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
20ce0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
20cf0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
20d00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20d10 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
20d20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
20d30 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
20d40 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
20d50 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
20d60 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
20d70 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
20d80 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
20d90 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
20da0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
20db0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
20dc0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
20dd0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
20de0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
20df0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
20e00 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
20e10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
20e20 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
20e30 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
20e40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20e50 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
20e60 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
20e70 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
20e80 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
20e90 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
20ea0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
20eb0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
20ec0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
20ed0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
20ee0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
20ef0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
20f00 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
20f10 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
20f20 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
20f30 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
20f40 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
20f50 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
20f60 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
20f70 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
20f80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20f90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
20fa0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
20fb0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
20fc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20fd0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
20fe0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
20ff0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
21000 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21010 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21020 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
21030 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
21040 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21050 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21060 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21070 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
21080 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
21090 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
210a0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
210b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
210c0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
210d0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
210e0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
210f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21100 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21110 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
21120 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
21130 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
21140 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21150 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21160 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
21170 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
21180 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
21190 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
211a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
211b0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
211c0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
211d0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
211e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
211f0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21200 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
21210 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
21220 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21230 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21240 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
21250 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
21260 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21270 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21280 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21290 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
212a0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
212b0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
212c0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
212d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
212e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
212f0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
21300 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21310 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21320 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21330 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
21340 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
21350 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
21360 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21370 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21380 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
21390 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
213a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
213b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
213c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
213d0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
213e0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
213f0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
21400 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21410 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21420 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
21430 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
21440 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
21450 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21460 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21470 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
21480 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
21490 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
214a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
214b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
214c0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
214d0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
214e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
214f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21510 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
21520 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
21530 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21540 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
21560 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
21570 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
21580 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
21590 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
215a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
215b0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
215c0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
215d0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
215e0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
215f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
21600 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
21610 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
21620 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
21630 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21640 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
21650 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
21660 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
21670 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
21680 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21690 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
216a0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
216b0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
216c0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
216d0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
216e0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
216f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
21700 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
21710 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21720 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21730 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
21740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
21750 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
21760 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
21770 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21780 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
21790 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
217a0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
217b0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
217c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
217d0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
217e0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
217f0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
21800 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21810 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21820 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
21830 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
21840 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21850 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21860 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21870 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
21880 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
21890 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
218a0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
218b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
218c0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
218d0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
218e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
218f0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
21900 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21910 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
21920 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
21930 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21940 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
21950 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21960 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
21970 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
21980 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
21990 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
219a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
219b0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
219c0 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
219d0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
219e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
219f0 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
21a00 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
21a10 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
21a20 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
21a30 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
21a40 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
21a50 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
21a60 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
21a70 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
21a80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
21a90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
21aa0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
21ab0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
21ac0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
21ad0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
21ae0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
21af0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
21b00 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
21b10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21b20 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
21b30 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
21b40 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
21b50 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
21b60 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
21b70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
21b80 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
21b90 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
21ba0 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
21bb0 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
21bc0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
21bd0 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
21be0 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
21bf0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
21c00 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
21c10 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
21c20 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
21c30 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
21c40 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
21c50 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
21c60 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  gger.)^.**.** ^T
21c70 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
21c80 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
21c90 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
21ca0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
21cb0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
21cc0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
21cd0 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
21ce0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
21cf0 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
21d00 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
21d10 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
21d20 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
21d30 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
21d40 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
21d50 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
21d60 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
21d70 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
21d80 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
21d90 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
21da0 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
21db0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
21dc0 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
21dd0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
21de0 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
21df0 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
21e00 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
21e10 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
21e20 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
21e30 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
21e40 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
21e50 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
21e60 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
21e70 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
21e80 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
21e90 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
21ea0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
21eb0 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
21ec0 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
21ed0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
21ee0 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
21ef0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
21f00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
21f10 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
21f20 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
21f30 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
21f40 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
21f50 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  id*);.SQLITE_API
21f60 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45   SQLITE_EXPERIME
21f70 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
21f80 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
21f90 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
21fa0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
21fb0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
21fc0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
21fd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21fe0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
21ff0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
22000 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
22010 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
22020 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
22030 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
22040 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
22050 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
22060 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
22070 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
22080 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
22090 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
220a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
220b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
220c0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
220d0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
220e0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
220f0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
22100 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
22110 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
22120 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
22130 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
22140 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
22150 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
22160 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
22170 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
22180 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
22190 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
221a0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
221b0 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  N is the number 
221c0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
221d0 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
221e0 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
221f0 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
22200 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
22210 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
22220 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a  e callback X..**
22230 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
22240 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
22250 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
22260 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
22270 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
22280 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
22290 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
222a0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
222b0 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
222c0 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
222d0 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
222e0 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
222f0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
22300 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
22310 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
22320 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
22330 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
22340 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
22350 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
22360 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
22370 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
22380 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
22390 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
223a0 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
223b0 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
223c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
223d0 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
223e0 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
223f0 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
22400 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
22410 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
22420 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
22430 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
22440 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
22450 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22460 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
22470 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
22480 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
22490 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
224a0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
224b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
224c0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
224d0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
224e0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
224f0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
22500 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
22510 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
22520 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
22530 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
22540 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
22550 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
22560 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
22570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22580 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
22590 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
225a0 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
225b0 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
225c0 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
225d0 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
225e0 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
225f0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
22600 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
22610 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
22620 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
22630 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
22640 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
22650 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
22660 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
22670 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
22680 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
22690 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
226a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
226b0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
226c0 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
226d0 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
226e0 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
226f0 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
22700 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
22710 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
22720 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
22730 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
22740 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
22750 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
22760 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
22770 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
22780 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
22790 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
227a0 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
227b0 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
227c0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
227d0 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
227e0 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
227f0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
22800 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
22810 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
22820 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
22830 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
22840 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
22850 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
22860 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
22870 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
22880 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
22890 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
228a0 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
228b0 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
228c0 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
228d0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
228e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
228f0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
22900 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
22910 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
22920 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
22930 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33  -8 if.** sqlite3
22940 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
22950 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
22960 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54  called and.** UT
22970 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
22980 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
22990 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
229a0 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ) is used..**.**
229b0 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
229c0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
229d0 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
229e0 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
229f0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
22a00 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
22a10 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
22a20 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
22a30 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
22a40 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
22a50 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
22a60 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
22a70 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
22a80 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
22a90 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
22aa0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
22ab0 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
22ac0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
22ad0 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
22ae0 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
22af0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
22b00 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
22b10 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
22b20 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
22b30 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
22b40 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
22b50 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
22b60 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
22b70 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
22b80 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
22b90 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
22ba0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
22bb0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
22bc0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
22bd0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
22be0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
22bf0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
22c00 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
22c10 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
22c20 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
22c30 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
22c40 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
22c50 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
22c60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
22c70 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
22c80 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
22c90 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
22ca0 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
22cb0 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
22cc0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
22cd0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
22ce0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
22cf0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
22d00 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
22d10 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
22d20 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
22d30 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
22d40 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
22d50 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
22d60 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
22d70 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
22d80 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
22d90 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
22da0 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
22db0 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
22dc0 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
22dd0 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
22de0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
22df0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
22e00 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
22e10 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
22e20 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
22e30 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
22e40 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
22e50 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
22e60 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
22e70 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
22e80 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
22e90 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
22ea0 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
22eb0 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
22ec0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
22ed0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
22ee0 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
22ef0 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
22f00 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
22f10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
22f20 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
22f30 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
22f40 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
22f50 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
22f60 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
22f70 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
22f80 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
22f90 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
22fa0 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
22fb0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
22fc0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
22fd0 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
22fe0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
22ff0 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
23000 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
23010 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
23020 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
23030 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
23040 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
23050 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
23060 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
23070 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
23080 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
23090 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
230a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
230b0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
230c0 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
230d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
230e0 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
230f0 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
23100 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
23110 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
23120 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
23130 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
23140 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
23150 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
23160 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
23170 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
23180 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
23190 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
231a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
231b0 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
231c0 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
231d0 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
231e0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
231f0 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
23200 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
23210 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
23220 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
23230 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
23240 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
23250 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
23260 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
23270 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
23280 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
23290 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
232a0 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
232b0 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
232c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
232d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
232e0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
232f0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
23300 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
23310 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
23320 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
23330 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
23340 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
23350 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
23360 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
23370 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
23380 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
23390 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
233a0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
233b0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
233c0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
233d0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
233e0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
233f0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
23400 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
23410 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
23420 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
23430 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
23440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
23450 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
23460 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
23470 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
23480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23490 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
234a0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
234b0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
234c0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
234d0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
234e0 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
234f0 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
23500 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
23510 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
23520 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
23530 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
23540 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
23550 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
23560 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
23570 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
23580 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
23590 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
235a0 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
235b0 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
235c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
235d0 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
235e0 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
235f0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
23600 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
23610 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
23620 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
23630 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
23640 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
23650 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
23660 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
23670 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
23680 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
23690 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
236a0 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
236b0 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
236c0 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
236d0 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
236e0 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
236f0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
23700 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
23710 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
23720 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
23730 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
23740 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
23750 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
23760 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
23770 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
23780 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
23790 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
237a0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
237b0 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
237c0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
237d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
237e0 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
237f0 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
23800 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
23810 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
23820 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
23830 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
23840 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
23850 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
23860 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
23870 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
23880 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
23890 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
238a0 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
238b0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
238c0 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
238d0 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
238e0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
238f0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
23900 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
23910 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
23920 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
23930 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
23940 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
23950 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
23960 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
23970 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
23980 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
23990 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
239a0 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
239b0 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
239c0 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
239d0 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
239e0 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
239f0 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
23a00 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
23a10 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
23a20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
23a30 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
23a40 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
23a50 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
23a60 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
23a70 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
23a80 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
23a90 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
23aa0 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
23ab0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
23ac0 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
23ad0 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
23ae0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
23af0 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
23b00 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
23b10 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
23b20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
23b30 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
23b40 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
23b50 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
23b60 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
23b70 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
23b80 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
23b90 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
23ba0 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
23bb0 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
23bc0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
23bd0 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
23be0 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
23bf0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
23c00 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
23c10 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74  * ^On windows, t
23c20 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
23c30 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
23c40 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
23c50 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
23c60 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
23c70 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
23c80 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
23c90 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
23ca0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
23cb0 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
23cc0 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
23cd0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
23ce0 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
23cf0 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
23d00 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
23d10 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
23d20 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
23d30 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
23d40 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
23d50 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
23d60 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
23d70 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
23d80 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
23d90 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
23da0 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
23db0 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
23dc0 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
23dd0 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
23de0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
23df0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
23e00 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
23e10 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
23e20 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
23e30 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
23e40 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
23e50 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
23e60 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
23e70 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
23e80 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
23e90 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
23ea0 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
23eb0 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
23ec0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23ed0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
23ee0 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
23ef0 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
23f00 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
23f10 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
23f20 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
23f30 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
23f40 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
23f50 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
23f60 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
23f70 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23f80 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
23f90 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
23fa0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
23fb0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
23fc0 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
23fd0 20 6f 72 0a 2a 2a 20 20 20 20 20 22 72 77 63 22   or.**     "rwc"
23fe0 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
23ff0 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
24000 68 65 72 20 76 61 6c 75 65 20 69 73 20 61 6e 20  her value is an 
24010 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
24020 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
24030 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
24040 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
24050 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
24060 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
24070 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
24080 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
24090 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
240a0 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
240b0 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
240c0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
240d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2e  e3_prepare_v2().
240e0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
240f0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
24100 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
24110 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
24120 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
24130 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
24140 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
24150 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
24160 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
24170 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
24180 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
24190 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
241a0 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
241b0 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
241c0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
241d0 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
241e0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
241f0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
24200 5f 43 52 45 41 54 45 2e 20 5e 49 66 20 73 71 6c  _CREATE. ^If sql
24210 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
24220 73 20 0a 2a 2a 20 20 20 20 20 75 73 65 64 2c 20  s .**     used, 
24230 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  it is an error t
24240 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
24250 65 20 66 6f 72 20 74 68 65 20 6d 6f 64 65 20 70  e for the mode p
24260 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
24270 20 0a 2a 2a 20 20 20 20 20 6c 65 73 73 20 72 65   .**     less re
24280 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
24290 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
242a0 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
242b0 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 0a  d as the third .
242c0 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72  **     parameter
242d0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
242e0 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
242f0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
24300 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
24310 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
24320 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
24330 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
24340 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
24350 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
24360 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
24370 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
24380 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
24390 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
243a0 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
243b0 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
243c0 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
243d0 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
243e0 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
243f0 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
24400 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
24410 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
24420 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
24430 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
24440 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24450 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
24460 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
24470 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
24480 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
24490 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
244a0 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
244b0 62 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 73  behaviour reques
244c0 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
244d0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
244e0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
244f0 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
24500 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
24510 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
24520 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
24530 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
24540 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
24550 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
24560 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
24570 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
24580 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
24590 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
245a0 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
245b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
245c0 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
245d0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
245e0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
245f0 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
24600 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
24610 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
24620 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
24630 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
24640 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
24650 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
24660 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
24670 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
24680 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
24690 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
246a0 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
246b0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
246c0 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
246d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
246e0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
246f0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
24700 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
24710 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
24720 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24730 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
24740 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
24750 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
24760 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
24770 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
24780 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
24790 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
247a0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
247b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
247c0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
247d0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
247e0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
247f0 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
24800 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
24810 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
24820 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
24830 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
24840 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
24850 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
24860 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
24870 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
24880 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
24890 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
248a0 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
248b0 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
248c0 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
248d0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
248e0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
248f0 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
24900 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
24910 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
24920 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
24930 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
24940 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
24950 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
24960 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
24970 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
24980 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
24990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
249a0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
249b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
249c0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
249d0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
249e0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
249f0 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
24a00 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
24a10 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
24a20 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
24a30 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
24a40 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
24a50 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
24a60 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
24a70 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
24a80 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
24a90 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
24aa0 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
24ab0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
24ac0 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
24ad0 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a  ix-nolock <td>.*
24ae0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
24af0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
24b00 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
24b10 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
24b20 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a  unix-nolock"..**
24b30 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
24b40 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
24b50 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
24b60 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
24b70 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
24b80 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
24b90 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
24ba0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
24bb0 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
24bc0 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
24bd0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
24be0 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
24bf0 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
24c00 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
24c10 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
24c20 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
24c30 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
24c40 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
24c50 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
24c60 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
24c70 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
24c80 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
24c90 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
24ca0 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
24cb0 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
24cc0 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
24cd0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
24ce0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
24cf0 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
24d00 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
24d10 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
24d20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
24d30 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
24d40 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
24d50 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
24d60 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
24d70 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
24d80 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
24d90 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
24da0 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
24db0 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
24dc0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
24dd0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
24de0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
24df0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
24e00 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
24e10 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
24e20 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
24e30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
24e40 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
24e50 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
24e60 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
24e70 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
24e80 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
24e90 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
24ea0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
24eb0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
24ec0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
24ed0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
24ee0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
24ef0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
24f00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
24f10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24f20 29 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )..*/.SQLITE_API
24f30 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
24f40 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
24f50 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
24f60 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
24f70 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
24f80 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
24f90 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
24fa0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
24fb0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
24fc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
24fd0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
24fe0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
24ff0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
25000 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
25010 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
25020 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
25030 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
25040 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
25050 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
25060 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
25070 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
25080 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
25090 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
250a0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
250b0 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
250c0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
250d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
250e0 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
250f0 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
25100 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
25110 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
25120 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
25130 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
25140 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
25150 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
25160 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
25170 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
25180 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
25190 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
251a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
251b0 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
251c0 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
251d0 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
251e0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
251f0 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
25200 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
25210 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
25220 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
25230 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
25240 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
25250 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
25260 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
25270 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
25280 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
25290 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
252a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
252b0 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
252c0 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
252d0 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
252e0 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
252f0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
25300 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
25310 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
25320 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
25330 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
25340 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
25350 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
25360 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
25370 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
25380 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
25390 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
253a0 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
253b0 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
253c0 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
253d0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
253e0 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
253f0 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
25400 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
25410 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
25420 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
25430 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
25440 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
25450 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
25460 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
25470 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
25480 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
25490 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
254a0 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
254b0 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
254c0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
254d0 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
254e0 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
254f0 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
25500 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
25510 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
25520 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
25530 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
25540 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
25550 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
25560 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
25570 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
25580 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
25590 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
255a0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
255b0 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
255c0 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
255d0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
255e0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
255f0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
25600 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
25610 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
25620 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
25630 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
25640 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
25650 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
25660 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
25670 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
25680 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
25690 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
256a0 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
256b0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
256c0 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
256d0 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
256e0 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
256f0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
25700 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
25710 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
25720 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
25730 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
25740 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
25750 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
25760 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
25770 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
25780 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
25790 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
257a0 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
257b0 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
257c0 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
257d0 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
257e0 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
257f0 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
25800 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
25810 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
25820 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
25830 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
25840 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
25850 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
25860 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
25870 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
25880 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
25890 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
258a0 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
258b0 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
258c0 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
258d0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
258e0 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
258f0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
25900 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
25910 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
25920 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
25930 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
25940 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
25950 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
25960 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
25970 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
25980 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
25990 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51  har *zParam);.SQ
259a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
259b0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
259c0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
259d0 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
259e0 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
259f0 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ault);.SQLITE_AP
25a00 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
25a10 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
25a20 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
25a30 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
25a40 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
25a50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
25a60 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
25a70 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
25a80 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
25a90 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
25aa0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
25ab0 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
25ac0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
25ad0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
25ae0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
25af0 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
25b00 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
25b10 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
25b20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25b30 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
25b40 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
25b50 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
25b60 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
25b70 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
25b80 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
25b90 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
25ba0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
25bb0 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
25bc0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
25bd0 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
25be0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
25bf0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
25c00 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
25c10 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
25c20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
25c30 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
25c40 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
25c50 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
25c60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
25c70 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
25c80 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
25c90 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
25ca0 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
25cb0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
25cc0 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
25cd0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
25ce0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
25cf0 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
25d00 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
25d10 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
25d20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
25d30 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
25d40 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
25d50 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
25d60 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
25d70 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
25d80 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
25d90 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
25da0 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
25db0 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
25dc0 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
25dd0 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
25de0 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
25df0 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
25e00 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
25e10 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
25e20 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
25e30 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
25e40 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
25e50 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
25e60 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
25e70 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
25e80 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
25e90 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
25ea0 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
25eb0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
25ec0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
25ed0 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
25ee0 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
25ef0 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
25f00 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
25f10 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
25f20 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
25f30 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
25f40 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
25f50 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
25f60 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
25f70 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
25f80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25f90 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
25fa0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
25fb0 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
25fc0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
25fd0 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
25fe0 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
25ff0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
26000 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
26010 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
26020 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
26030 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
26040 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
26050 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
26060 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
26070 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
26080 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
26090 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
260a0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
260b0 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
260c0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
260d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
260e0 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
260f0 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
26100 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
26110 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
26120 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
26130 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
26140 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
26150 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
26160 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
26170 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
26180 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
26190 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
261a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
261b0 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
261c0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
261d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
261e0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
261f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
26200 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
26210 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
26220 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26230 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
26240 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
26250 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
26260 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
26270 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
26280 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
26290 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
262a0 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
262b0 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
262c0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
262d0 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
262e0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
262f0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
26300 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
26310 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
26320 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
26330 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
26340 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
26350 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
26360 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
26370 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26380 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
26390 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
263a0 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
263b0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
263c0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
263d0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
263e0 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
263f0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
26400 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
26410 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
26420 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
26430 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
26440 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
26450 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
26460 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
26470 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
26480 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
26490 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
264a0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
264b0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
264c0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
264d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
264e0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
264f0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
26500 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
26510 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
26520 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
26530 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
26540 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
26550 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
26560 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
26570 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
26580 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
26590 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
265a0 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
265b0 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
265c0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
265d0 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
265e0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
265f0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
26600 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
26610 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
26620 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
26630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
26640 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
26650 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
26660 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
26670 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
26680 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
26690 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
266a0 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
266b0 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
266c0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
266d0 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
266e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
266f0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
26700 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
26710 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
26720 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
26730 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
26740 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
26750 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
26760 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
26770 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
26780 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
26790 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
267a0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
267b0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
267c0 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
267d0 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
267e0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
267f0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
26800 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
26810 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
26820 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
26830 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
26840 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
26850 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
26860 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
26870 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
26880 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
26890 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
268a0 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
268b0 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
268c0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
268d0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
268e0 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
268f0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
26900 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
26910 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
26920 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
26930 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
26940 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
26950 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
26960 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
26970 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
26980 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
26990 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
269a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
269b0 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
269c0 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
269d0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
269e0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
269f0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
26a00 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
26a10 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
26a20 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
26a30 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
26a40 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
26a50 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
26a60 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
26a70 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
26a80 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
26a90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
26aa0 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
26ab0 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
26ac0 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
26ad0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
26ae0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
26af0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
26b00 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
26b10 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
26b20 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
26b30 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
26b40 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
26b50 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
26b60 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
26b70 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
26b80 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
26b90 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
26ba0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
26bb0 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
26bc0 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
26bd0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
26be0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
26bf0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
26c00 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
26c10 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
26c20 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
26c30 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
26c40 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
26c50 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
26c60 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
26c70 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
26c80 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
26c90 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
26ca0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
26cb0 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
26cc0 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
26cd0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
26ce0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
26cf0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
26d00 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
26d10 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
26d20 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
26d30 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
26d40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d   int sqlite3_lim
26d50 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
26d60 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
26d70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26d80 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
26d90 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
26da0 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
26db0 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
26dc0 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
26dd0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
26de0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
26df0 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
26e00 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
26e10 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
26e20 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
26e30 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
26e40 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
26e50 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
26e60 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
26e70 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
26e80 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
26e90 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
26ea0 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
26eb0 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
26ec0 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
26ed0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
26ee0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
26ef0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
26f00 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
26f10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26f20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
26f30 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
26f40 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
26f50 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
26f60 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26f70 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
26f80 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26f90 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
26fa0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26fb0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
26fc0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
26fd0 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
26fe0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26ff0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
27000 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
27010 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
27020 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
27030 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
27040 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
27050 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
27060 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
27070 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
27080 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
27090 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
270a0 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
270b0 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
270c0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
270d0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
270e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
270f0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
27100 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
27110 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
27120 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27130 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
27140 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
27150 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
27160 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
27170 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
27180 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
27190 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
271a0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
271b0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
271c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
271d0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
271e0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
271f0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
27200 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
27210 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
27220 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
27230 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
27240 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
27250 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
27260 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
27270 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
27280 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
27290 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
272a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
272b0 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
272c0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
272d0 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
272e0 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
272f0 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
27300 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
27310 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
27320 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
27330 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
27340 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
27350 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
27360 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
27370 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
27380 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
27390 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
273a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
273b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
273c0 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
273d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
273e0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
273f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
27400 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
27410 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
27420 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
27430 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
27440 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
27450 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
27460 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
27470 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
27480 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27490 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
274a0 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
274b0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
274c0 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
274d0 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
274e0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
274f0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
27500 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
27510 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
27520 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
27530 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
27540 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
27550 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
27560 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
27570 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
27580 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27590 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
275a0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
275b0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
275c0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
275d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
275e0 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
275f0 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
27600 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
27610 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
27620 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
27630 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27640 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
27650 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
27660 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
27670 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
27680 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
27690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
276a0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
276b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
276c0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
276d0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
276e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
276f0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
27700 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
27710 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
27720 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
27730 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
27740 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
27750 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
27760 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
27770 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
27780 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
27790 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
277a0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
277b0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
277c0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
277d0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
277e0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
277f0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
27800 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27810 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
27820 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f             10../
27830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
27840 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
27850 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
27860 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
27870 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
27880 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
27890 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
278a0 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
278b0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
278c0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
278d0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
278e0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
278f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
27900 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
27910 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
27920 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
27930 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
27940 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
27950 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
27960 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
27970 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
27980 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
27990 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
279a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
279b0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
279c0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
279d0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
279e0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
279f0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
27a00 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
27a10 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
27a20 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
27a30 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
27a40 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
27a50 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
27a60 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
27a70 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
27a80 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
27a90 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
27aa0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
27ab0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
27ac0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
27ad0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
27ae0 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
27af0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
27b00 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
27b10 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
27b20 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
27b30 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
27b40 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
27b50 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
27b60 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
27b70 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
27b80 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
27b90 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
27ba0 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
27bb0 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
27bc0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
27bd0 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
27be0 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
27bf0 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
27c00 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
27c10 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
27c20 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
27c30 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
27c40 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
27c50 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
27c60 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
27c70 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
27c80 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
27c90 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
27ca0 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
27cb0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
27cc0 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
27cd0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
27ce0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
27cf0 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
27d00 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
27d10 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68  ator bytes as th
27d20 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20  is saves SQLite 
27d30 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a  from having to.*
27d40 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  * make a copy of
27d50 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
27d60 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  g..**.** ^If pzT
27d70 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
27d80 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
27d90 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
27da0 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
27db0 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
27dc0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
27dd0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
27de0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
27df0 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
27e00 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
27e10 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
27e20 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
27e30 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
27e40 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
27e50 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
27e60 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
27e70 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
27e80 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
27e90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
27ea0 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
27eb0 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
27ec0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
27ed0 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
27ee0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
27ef0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
27f00 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
27f10 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
27f20 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
27f30 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
27f40 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
27f50 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
27f60 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
27f70 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
27f80 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
27f90 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
27fa0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
27fb0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
27fc0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
27fd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
27fe0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
27ff0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
28000 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
28010 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
28020 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
28030 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
28040 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
28050 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
28060 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
28070 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
28080 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
28090 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
280a0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
280b0 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
280c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
280d0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
280e0 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
280f0 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
28100 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
28110 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
28120 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
28130 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
28140 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
28150 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
28160 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
28170 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
28180 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
28190 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
281a0 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
281b0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
281c0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
281d0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
281e0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
281f0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
28200 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
28210 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
28220 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
28230 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
28240 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
28250 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
28260 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
28270 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
28280 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
28290 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
282a0 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
282b0 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
282c0 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
282d0 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
282e0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
282f0 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
28300 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
28310 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a  o run it again..
28320 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
28330 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
28340 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
28350 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
28360 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
28370 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
28380 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
28390 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
283a0 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
283b0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
283c0 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
283d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
283e0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
283f0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
28400 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
28410 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
28420 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
28430 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
28440 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
28450 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28460 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
28470 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
28480 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
28490 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
284a0 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
284b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
284c0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
284d0 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
284e0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
284f0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
28500 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
28510 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
28520 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
28530 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
28540 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
28550 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
28560 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
28570 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
28580 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
28590 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
285a0 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
285b0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
285c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
285d0 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
285e0 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
285f0 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
28600 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
28610 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
28620 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
28630 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
28640 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
28650 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
28660 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
28670 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
28680 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
28690 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
286a0 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
286b0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
286c0 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
286d0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
286e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
286f0 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
28700 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
28710 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
28720 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
28730 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
28740 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
28750 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
28760 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
28770 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
28780 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
28790 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74  is enabled..** t
287a0 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  he .** </li>.** 
287b0 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ol>.*/.SQLITE_
287c0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
287d0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
287e0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
287f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
28800 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28810 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
28820 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
28830 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
28840 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
28850 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
28860 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
28870 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
28880 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
28890 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
288a0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
288b0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
288c0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
288d0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
288e0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
288f0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
28900 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
28910 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
28920 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
28930 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
28940 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
28950 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
28960 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
28970 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
28980 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
28990 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
289a0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
289b0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
289c0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
289d0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
289e0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
289f0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
28a00 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
28a10 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
28a20 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
28a30 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
28a40 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
28a50 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
28a60 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
28a70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
28a80 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
28a90 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
28aa0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
28ab0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
28ac0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
28ad0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
28ae0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
28af0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
28b00 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
28b10 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
28b20 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
28b30 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
28b40 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
28b50 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
28b60 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
28b70 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
28b80 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
28b90 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
28ba0 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
28bb0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
28bc0 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
28bd0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
28be0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
28bf0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
28c00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
28c10 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
28c20 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
28c30 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
28c40 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
28c50 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
28c60 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
28c70 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
28c80 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
28c90 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
28ca0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
28cb0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
28cc0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
28cd0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
28ce0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
28cf0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
28d00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
28d10 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
28d20 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
28d30 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
28d40 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
28d50 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
28d60 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
28d70 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
28d80 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
28d90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28da0 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
28db0 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
28dc0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
28dd0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
28de0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
28df0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28e00 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  v2()]..*/.SQLITE
28e10 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
28e20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
28e30 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
28e40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28e50 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
28e60 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
28e70 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
28e80 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
28e90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
28ea0 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
28eb0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
28ec0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
28ed0 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
28ee0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28ef0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
28f00 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
28f10 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
28f20 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
28f30 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
28f40 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
28f50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
28f60 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
28f70 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
28f80 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
28f90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
28fa0 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
28fb0 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
28fc0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
28fd0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
28fe0 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
28ff0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
29000 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
29010 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
29020 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
29030 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
29040 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
29050 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
29060 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
29070 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
29080 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
29090 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
290a0 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
290b0 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
290c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
290d0 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
290e0 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
290f0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
29100 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
29110 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
29120 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
29130 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
29140 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
29150 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
29160 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
29170 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
29180 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
29190 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
291a0 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
291b0 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
291c0 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
291d0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
291e0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
291f0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
29200 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
29210 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
29220 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
29230 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
29240 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
29250 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
29260 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
29270 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
29280 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
29290 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
292a0 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
292b0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
292c0 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
292d0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
292e0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
292f0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
29300 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
29310 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
29320 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
29330 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
29340 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
29350 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
29360 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
29370 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
29380 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
29390 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
293a0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
293b0 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
293c0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
293d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
293e0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
293f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
29400 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
29410 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29420 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
29430 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29440 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
29450 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
29460 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29470 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
29480 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
29490 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
294a0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
294b0 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
294c0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
294d0 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
294e0 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
294f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29500 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
29510 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
29520 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
29530 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
29540 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
29550 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
29560 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
29570 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
29580 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
29590 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
295a0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
295b0 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
295c0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
295d0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
295e0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
295f0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
29600 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
29610 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
29620 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
29630 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
29640 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
29650 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
29660 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
29670 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
29680 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
29690 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
296a0 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
296b0 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
296c0 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
296d0 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
296e0 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
296f0 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
29700 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
29710 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
29720 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45   open..*/.SQLITE
29730 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29740 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
29750 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
29760 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
29770 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
29780 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
29790 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
297a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
297b0 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
297c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
297d0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
297e0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
297f0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
29800 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
29810 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
29820 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
29830 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
29840 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
29850 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
29860 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
29870 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
29880 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
29890 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
298a0 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
298b0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
298c0 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
298d0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
298e0 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
298f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
29900 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
29910 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
29920 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
29930 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
29940 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
29950 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
29960 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
29970 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
29980 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
29990 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
299a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
299b0 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
299c0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
299d0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
299e0 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
299f0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
29a00 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
29a10 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
29a20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
29a30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
29a40 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
29a50 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
29a60 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
29a70 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
29a80 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
29a90 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
29aa0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
29ab0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
29ac0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
29ad0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
29ae0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
29af0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
29b00 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
29b10 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
29b20 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
29b30 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
29b40 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
29b50 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
29b60 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
29b70 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
29b80 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
29b90 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
29ba0 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
29bb0 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
29bc0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
29bd0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
29be0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
29bf0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
29c00 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
29c10 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
29c20 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
29c30 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
29c40 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
29c50 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
29c60 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
29c70 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
29c80 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
29c90 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
29ca0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
29cb0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
29cc0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
29cd0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
29ce0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
29cf0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
29d00 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
29d10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29d20 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
29d30 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
29d40 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
29d50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
29d60 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
29d70 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
29d80 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
29d90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
29da0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
29db0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
29dc0 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
29dd0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
29de0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29df0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
29e00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
29e10 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
29e20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
29e30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29e40 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
29e50 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
29e60 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
29e70 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
29e80 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
29e90 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
29ea0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
29eb0 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
29ec0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
29ed0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
29ee0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
29ef0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
29f00 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
29f10 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
29f20 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
29f30 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
29f40 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
29f50 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
29f60 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
29f70 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
29f80 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
29f90 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
29fa0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
29fb0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
29fc0 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
29fd0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
29fe0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
29ff0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2a000 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2a010 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2a020 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2a030 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2a040 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2a050 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2a060 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2a070 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2a080 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2a090 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2a0a0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2a0b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2a0c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2a0d0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2a0e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2a0f0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2a100 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2a110 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2a120 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2a130 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2a140 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2a150 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2a160 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2a170 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2a180 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2a190 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2a1a0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2a1b0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2a1c0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2a1d0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2a1e0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2a1f0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2a200 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2a210 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2a220 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2a230 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2a240 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
2a250 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
2a260 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
2a270 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
2a280 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2a290 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
2a2a0 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
2a2b0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
2a2c0 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
2a2d0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
2a2e0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
2a2f0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
2a300 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
2a310 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
2a320 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
2a330 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
2a340 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
2a350 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
2a360 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
2a370 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
2a380 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
2a390 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
2a3a0 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
2a3b0 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
2a3c0 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
2a3d0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
2a3e0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
2a3f0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
2a400 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
2a410 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
2a420 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
2a430 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2a440 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2a450 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
2a460 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2a470 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2a480 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2a490 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
2a4a0 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
2a4b0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
2a4c0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
2a4d0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
2a4e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a4f0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
2a500 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
2a510 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2a520 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2a530 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
2a540 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
2a550 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
2a560 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
2a570 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2a580 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
2a590 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
2a5a0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
2a5b0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
2a5c0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2a5d0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
2a5e0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
2a5f0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
2a600 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
2a610 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
2a620 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
2a630 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
2a640 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
2a650 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a660 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2a670 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
2a680 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
2a690 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
2a6a0 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
2a6b0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
2a6c0 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
2a6d0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
2a6e0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
2a6f0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
2a700 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
2a710 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2a720 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
2a730 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
2a740 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2a750 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2a760 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
2a770 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
2a780 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
2a790 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
2a7a0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
2a7b0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
2a7c0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2a7d0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2a7e0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
2a7f0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
2a800 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2a810 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
2a820 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
2a830 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
2a840 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2a850 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
2a860 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2a870 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2a880 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
2a890 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
2a8a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2a8b0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2a8c0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2a8d0 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
2a8e0 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
2a8f0 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
2a900 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
2a910 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
2a920 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a930 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20  t16() then that 
2a940 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2a950 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
2a960 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
2a970 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
2a980 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
2a990 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
2a9a0 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
2a9b0 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
2a9c0 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
2a9d0 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
2a9e0 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
2a9f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2aa00 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2aa10 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
2aa20 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
2aa30 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
2aa40 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
2aa50 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
2aa60 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
2aa70 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
2aa80 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
2aa90 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
2aaa0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
2aab0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
2aac0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2aad0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
2aae0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
2aaf0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2ab00 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
2ab10 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
2ab20 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2ab30 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
2ab40 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
2ab50 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
2ab60 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
2ab70 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
2ab80 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2ab90 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
2aba0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
2abb0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
2abc0 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
2abd0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2abe0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
2abf0 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
2ac00 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
2ac10 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
2ac20 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
2ac30 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
2ac40 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
2ac50 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
2ac60 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
2ac70 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
2ac80 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
2ac90 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
2aca0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
2acb0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2acc0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
2acd0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
2ace0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
2acf0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
2ad00 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
2ad10 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
2ad20 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
2ad30 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
2ad40 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2ad50 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
2ad60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ad70 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2ad80 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
2ad90 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
2ada0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
2adb0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
2adc0 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
2add0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
2ade0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
2adf0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
2ae00 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
2ae10 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
2ae20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
2ae30 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
2ae40 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
2ae50 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
2ae60 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
2ae70 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
2ae80 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
2ae90 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2aea0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
2aeb0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
2aec0 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
2aed0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
2aee0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
2aef0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
2af00 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2af10 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
2af20 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
2af30 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2af40 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
2af50 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
2af60 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
2af70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2af80 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
2af90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
2afa0 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
2afb0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2afc0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
2afd0 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
2afe0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2aff0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
2b000 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
2b010 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2b020 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
2b030 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
2b040 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
2b050 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b060 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
2b070 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
2b080 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
2b090 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2b0a0 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
2b0b0 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
2b0c0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
2b0d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
2b0e0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
2b0f0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
2b100 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
2b110 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
2b120 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b130 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
2b140 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2b150 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
2b160 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
2b170 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
2b180 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
2b190 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
2b1a0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2b1b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
2b1c0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
2b1d0 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
2b1e0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
2b1f0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
2b200 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
2b210 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2b220 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2b230 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
2b240 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b250 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2b260 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
2b270 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2b280 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2b290 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2b2a0 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
2b2b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2b2c0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
2b2d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2b2e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2b2f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
2b300 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2b310 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
2b320 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2b330 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2b340 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2b350 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49   int, int);.SQLI
2b360 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2b370 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
2b380 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b390 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
2b3a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2b3b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2b3c0 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
2b3d0 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
2b3e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2b3f0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
2b400 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2b410 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
2b420 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2b430 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2b440 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2b450 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2b460 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2b470 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2b480 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2b490 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2b4a0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
2b4b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b4c0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
2b4d0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2b4e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2b4f0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
2b500 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b510 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
2b520 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2b530 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
2b540 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
2b550 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
2b560 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
2b570 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
2b580 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
2b590 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2b5a0 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
2b5b0 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
2b5c0 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
2b5d0 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
2b5e0 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
2b5f0 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
2b600 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
2b610 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
2b620 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
2b630 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2b640 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
2b650 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
2b660 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
2b670 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
2b680 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
2b690 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
2b6a0 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
2b6b0 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
2b6c0 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
2b6d0 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
2b6e0 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
2b6f0 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
2b700 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
2b710 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
2b720 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
2b730 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
2b740 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
2b750 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
2b760 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
2b770 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2b780 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2b790 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2b7a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2b7b0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2b7c0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2b7d0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b7e0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2b7f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2b800 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b810 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
2b820 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2b830 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2b840 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
2b850 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  meter.**.** ^The
2b860 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2b870 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
2b880 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b890 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
2b8a0 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
2b8b0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2b8c0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b8d0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
2b8e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
2b8f0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
2b900 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2b910 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2b920 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
2b930 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
2b940 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
2b950 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2b960 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
2b970 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
2b980 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2b990 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
2b9a0 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
2b9b0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
2b9c0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
2b9d0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
2b9e0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2b9f0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
2ba00 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
2ba10 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
2ba20 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
2ba30 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
2ba40 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
2ba50 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
2ba60 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2ba70 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
2ba80 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2ba90 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
2baa0 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
2bab0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
2bac0 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
2bad0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
2bae0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
2baf0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
2bb00 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2bb10 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
2bb20 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
2bb30 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2bb40 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
2bb50 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
2bb60 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
2bb70 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
2bb80 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
2bb90 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2bba0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2bbb0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2bbc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2bbd0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2bbe0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2bbf0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2bc00 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2bc10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2bc20 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2bc30 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2bc40 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2bc50 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2bc60 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
2bc70 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
2bc80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
2bc90 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
2bca0 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
2bcb0 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
2bcc0 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
2bcd0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
2bce0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
2bcf0 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
2bd00 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
2bd10 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
2bd20 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
2bd30 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
2bd40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2bd50 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2bd60 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
2bd70 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
2bd80 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
2bd90 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
2bda0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
2bdb0 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
2bdc0 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
2bdd0 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
2bde0 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
2bdf0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
2be00 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
2be10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
2be20 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2be30 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2be40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2be50 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2be60 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2be70 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2be80 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2be90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2bea0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2beb0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2bec0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2bed0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
2bee0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
2bef0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
2bf00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bf10 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
2bf20 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
2bf30 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2bf40 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
2bf50 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
2bf60 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
2bf70 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
2bf80 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
2bf90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2bfa0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
2bfb0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2bfc0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
2bfd0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2bfe0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
2bff0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
2c000 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ULL..*/.SQLITE_A
2c010 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2c020 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
2c030 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2c040 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2c050 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
2c060 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2c070 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2c080 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2c090 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2c0a0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
2c0b0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
2c0c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2c0d0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
2c0e0 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
2c0f0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
2c100 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
2c110 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
2c120 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
2c130 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
2c140 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2c150 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2c160 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()].*/.SQLITE_AP
2c170 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2c180 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
2c190 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2c1a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c1b0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
2c1c0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2c1d0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2c1e0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2c1f0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
2c200 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
2c210 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
2c220 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2c230 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2c240 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
2c250 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
2c260 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2c270 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2c280 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2c290 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
2c2a0 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
2c2b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
2c2c0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2c2d0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2c2e0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
2c2f0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
2c300 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2c310 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2c320 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
2c330 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2c340 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2c350 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
2c360 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2c370 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
2c380 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
2c390 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
2c3a0 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
2c3b0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2c3c0 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
2c3d0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
2c3e0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2c3f0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
2c400 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
2c410 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2c420 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2c430 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2c440 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2c450 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2c460 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2c470 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2c480 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2c490 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2c4a0 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
2c4b0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2c4c0 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
2c4d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2c4e0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
2c4f0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
2c500 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
2c510 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
2c520 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
2c530 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
2c540 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
2c550 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
2c560 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
2c570 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
2c580 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2c590 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2c5a0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2c5b0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
2c5c0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2c5d0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
2c5e0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
2c5f0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
2c600 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
2c610 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
2c620 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
2c630 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2c640 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
2c650 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
2c660 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
2c670 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
2c680 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
2c690 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2c6a0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2c6b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
2c6c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2c6d0 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t N);.SQLITE_API
2c6e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2c6f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2c700 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2c710 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
2c720 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
2c730 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
2c740 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
2c750 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2c760 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
2c770 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
2c780 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
2c790 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
2c7a0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
2c7b0 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
2c7c0 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
2c7d0 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
2c7e0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2c7f0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
2c800 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2c810 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
2c820 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
2c830 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
2c840 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
2c850 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2c860 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
2c870 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
2c880 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
2c890 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
2c8a0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2c8b0 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
2c8c0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
2c8d0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2c8e0 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
2c8f0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2c900 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
2c910 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
2c920 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c930 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
2c940 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2c950 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2c960 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2c970 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2c980 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2c990 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2c9a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2c9b0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2c9c0 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2c9d0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
2c9e0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
2c9f0 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
2ca00 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
2ca10 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
2ca20 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
2ca30 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
2ca40 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
2ca50 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
2ca60 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
2ca70 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
2ca80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2ca90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2caa0 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
2cab0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2cac0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
2cad0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2cae0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2caf0 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
2cb00 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
2cb10 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
2cb20 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
2cb30 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
2cb40 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
2cb50 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
2cb60 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
2cb70 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
2cb80 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
2cb90 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
2cba0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2cbb0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2cbc0 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
2cbd0 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
2cbe0 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
2cbf0 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
2cc00 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
2cc10 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
2cc20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
2cc30 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
2cc40 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
2cc50 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2cc60 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
2cc70 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
2cc80 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
2cc90 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
2cca0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
2ccb0 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
2ccc0 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
2ccd0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
2cce0 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
2ccf0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
2cd00 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
2cd10 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
2cd20 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
2cd30 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
2cd40 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
2cd50 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
2cd60 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
2cd70 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
2cd80 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
2cd90 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
2cda0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
2cdb0 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
2cdc0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
2cdd0 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
2cde0 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
2cdf0 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
2ce00 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
2ce10 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2ce20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2ce30 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2ce40 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
2ce50 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
2ce60 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
2ce70 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
2ce80 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2ce90 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
2cea0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
2ceb0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2cec0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2ced0 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
2cee0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2cef0 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
2cf00 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
2cf10 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
2cf20 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
2cf30 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
2cf40 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
2cf50 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2cf60 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2cf70 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2cf80 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2cf90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2cfa0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2cfb0 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
2cfc0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2cfd0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2cfe0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2cff0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2d000 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2d010 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2d020 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2d030 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2d040 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2d050 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2d060 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2d070 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2d080 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
2d090 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2d0a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2d0b0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2d0c0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2d0d0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2d0e0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2d0f0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2d100 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2d110 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
2d120 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2d130 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d140 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
2d150 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
2d160 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  sult.**.** ^(The
2d170 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2d180 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2d190 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2d1a0 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
2d1b0 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
2d1c0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
2d1d0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2d1e0 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
2d1f0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
2d200 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
2d210 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
2d220 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
2d230 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
2d240 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
2d250 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
2d260 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
2d270 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
2d280 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2d290 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2d2a0 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
2d2b0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2d2c0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
2d2d0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2d2e0 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
2d2f0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2d300 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
2d310 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
2d320 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
2d330 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2d340 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
2d350 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
2d360 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
2d370 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
2d380 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
2d390 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
2d3a0 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
2d3b0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
2d3c0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
2d3d0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
2d3e0 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
2d3f0 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
2d400 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
2d410 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
2d420 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
2d430 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
2d440 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
2d450 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2d460 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
2d470 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
2d480 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
2d490 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
2d4a0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
2d4b0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
2d4c0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
2d4d0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
2d4e0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
2d4f0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
2d500 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2d510 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
2d520 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
2d530 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
2d540 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
2d550 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
2d560 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
2d570 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
2d580 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
2d590 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
2d5a0 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
2d5b0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
2d5c0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d5d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2d5e0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2d5f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2d600 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2d610 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2d620 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2d630 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2d640 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2d650 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
2d660 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
2d670 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  nt.**.** After a
2d680 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d690 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
2d6a0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
2d6b0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2d6c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2d6d0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2d6e0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
2d6f0 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
2d700 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
2d710 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2d720 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2d730 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
2d740 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
2d750 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
2d760 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
2d770 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
2d780 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
2d790 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
2d7a0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
2d7b0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2d7c0 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
2d7d0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
2d7e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
2d7f0 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
2d800 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
2d810 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
2d820 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2d830 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2d840 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2d850 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
2d860 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2d870 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2d880 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2d890 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
2d8a0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2d8b0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
2d8c0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2d8d0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
2d8e0 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
2d8f0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2d900 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
2d910 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
2d920 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
2d930 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2d940 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
2d950 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
2d960 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
2d970 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
2d980 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
2d990 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
2d9a0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
2d9b0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
2d9c0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2d9d0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
2d9e0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
2d9f0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
2da00 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
2da10 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
2da20 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
2da30 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
2da40 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
2da50 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
2da60 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
2da70 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
2da80 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
2da90 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
2daa0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
2dab0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
2dac0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
2dad0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
2dae0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
2daf0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
2db00 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
2db10 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
2db20 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2db30 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
2db40 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
2db50 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
2db60 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
2db70 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
2db80 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
2db90 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
2dba0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
2dbb0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
2dbc0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2dbd0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
2dbe0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
2dbf0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
2dc00 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
2dc10 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2dc20 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2dc30 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
2dc40 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
2dc50 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
2dc60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2dc70 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
2dc80 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2dc90 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
2dca0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
2dcb0 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
2dcc0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
2dcd0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
2dce0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
2dcf0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
2dd00 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
2dd10 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
2dd20 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
2dd30 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
2dd40 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
2dd50 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
2dd60 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
2dd70 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
2dd80 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
2dd90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2dda0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
2ddb0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
2ddc0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
2ddd0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
2dde0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
2ddf0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
2de00 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
2de10 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
2de20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
2de30 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
2de40 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2de50 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2de60 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
2de70 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
2de80 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
2de90 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2dea0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
2deb0 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
2dec0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
2ded0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2dee0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
2def0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
2df00 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
2df10 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
2df20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
2df30 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
2df40 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
2df50 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2df60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2df70 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
2df80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2df90 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
2dfa0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
2dfb0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2dfc0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
2dfd0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
2dfe0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
2dff0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
2e000 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
2e010 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
2e020 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
2e030 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
2e040 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
2e050 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
2e060 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e070 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
2e080 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
2e090 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2e0a0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
2e0b0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
2e0c0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
2e0d0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
2e0e0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2e0f0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
2e100 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
2e110 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
2e120 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e130 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
2e140 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
2e150 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
2e160 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
2e170 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
2e180 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
2e190 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
2e1a0 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
2e1b0 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
2e1c0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2e1d0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
2e1e0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
2e1f0 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
2e200 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
2e210 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2e220 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
2e230 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
2e240 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
2e250 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
2e260 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
2e270 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e280 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
2e290 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2e2a0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
2e2b0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2e2c0 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
2e2d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2e2e0 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73    But after vers
2e2f0 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71  ion 3.6.23.1, sq
2e300 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
2e310 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
2e320 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2e330 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2e340 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
2e350 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
2e360 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
2e370 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
2e380 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
2e390 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
2e3a0 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
2e3b0 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
2e3c0 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
2e3d0 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
2e3e0 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
2e3f0 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
2e400 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
2e410 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
2e420 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
2e430 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
2e440 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
2e450 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
2e460 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
2e470 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
2e480 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
2e490 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2e4a0 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
2e4b0 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
2e4c0 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
2e4d0 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
2e4e0 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
2e4f0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
2e500 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
2e510 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2e520 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
2e530 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
2e540 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
2e550 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e560 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2e570 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
2e580 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
2e590 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
2e5a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
2e5b0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
2e5c0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
2e5d0 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
2e5e0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
2e5f0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
2e600 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
2e610 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
2e620 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
2e630 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
2e640 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
2e650 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
2e660 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
2e670 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2e680 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2e690 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
2e6a0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
2e6b0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
2e6c0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
2e6d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e6e0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
2e6f0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
2e700 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
2e710 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
2e720 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
2e730 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
2e740 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
2e750 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
2e760 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2e770 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ded..*/.SQLITE_A
2e780 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
2e790 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
2e7a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2e7b0 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
2e7c0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
2e7d0 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
2e7e0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2e7f0 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
2e800 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2e810 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2e820 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
2e830 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2e840 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
2e850 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e860 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
2e870 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
2e880 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
2e890 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
2e8a0 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
2e8b0 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
2e8c0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
2e8d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
2e8e0 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
2e8f0 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
2e900 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2e910 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
2e920 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2e930 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2e940 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
2e950 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
2e960 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
2e970 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2e980 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
2e990 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
2e9a0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2e9b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2e9c0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
2e9d0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
2e9e0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2e9f0 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
2ea00 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
2ea10 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
2ea20 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2ea30 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2ea40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
2ea50 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
2ea60 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
2ea70 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
2ea80 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
2ea90 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
2eaa0 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
2eab0 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
2eac0 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
2ead0 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
2eae0 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
2eaf0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2eb00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2eb10 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
2eb20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2eb30 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
2eb40 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2eb50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2eb60 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
2eb70 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
2eb80 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
2eb90 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
2eba0 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
2ebb0 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
2ebc0 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
2ebd0 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
2ebe0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
2ebf0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2ec00 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
2ec10 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
2ec20 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
2ec30 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
2ec40 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
2ec50 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
2ec60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2ec70 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
2ec80 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
2ec90 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
2eca0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
2ecb0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
2ecc0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
2ecd0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
2ece0 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
2ecf0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
2ed00 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
2ed10 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
2ed20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
2ed30 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2ed40 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
2ed50 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
2ed60 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
2ed70 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
2ed80 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
2ed90 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
2eda0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
2edb0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
2edc0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
2edd0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2ede0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
2edf0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
2ee00 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
2ee10 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
2ee20 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
2ee30 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
2ee40 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
2ee50 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
2ee60 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
2ee70 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
2ee80 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
2ee90 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
2eea0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2eeb0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2eec0 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
2eed0 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e   set" interface.
2eee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2eef0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
2ef00 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2ef10 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
2ef20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
2ef30 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
2ef40 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
2ef50 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
2ef60 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
2ef70 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
2ef80 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ef90 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
2efa0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
2efb0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2efc0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
2efd0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
2efe0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2eff0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2f000 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
2f010 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
2f020 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2f030 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
2f040 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
2f050 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
2f060 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
2f070 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2f080 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2f090 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
2f0a0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
2f0b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2f0c0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2f0d0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
2f0e0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
2f0f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2f100 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
2f110 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2f120 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
2f130 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
2f140 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
2f150 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
2f160 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2f170 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
2f180 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2f190 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2f1a0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
2f1b0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
2f1c0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
2f1d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2f1e0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2f1f0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
2f200 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
2f210 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
2f220 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2f230 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
2f240 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
2f250 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
2f260 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2f270 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
2f280 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
2f290 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2f2a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2f2b0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
2f2c0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2f2d0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
2f2e0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
2f2f0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
2f300 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2f310 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
2f320 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f330 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2f340 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2f350 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
2f360 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2f370 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
2f380 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
2f390 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2f3a0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
2f3b0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2f3c0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2f3d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f3e0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2f3f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2f400 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
2f410 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2f420 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
2f430 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
2f440 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
2f450 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
2f460 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
2f470 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2f480 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
2f490 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
2f4a0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
2f4b0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
2f4c0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
2f4d0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
2f4e0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2f4f0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2f500 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
2f510 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
2f520 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
2f530 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
2f540 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
2f550 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
2f560 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
2f570 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
2f580 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f590 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
2f5a0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
2f5b0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2f5c0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
2f5d0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
2f5e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2f5f0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
2f600 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2f610 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
2f620 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2f630 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
2f640 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2f650 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f660 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2f670 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2f680 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2f690 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2f6a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2f6b0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
2f6c0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2f6d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f6e0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
2f6f0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2f700 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
2f710 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2f720 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2f730 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2f740 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2f750 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2f760 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
2f770 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2f780 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2f790 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2f7a0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
2f7b0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2f7c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2f7d0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2f7e0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2f7f0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2f800 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2f810 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
2f820 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
2f830 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2f840 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
2f850 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2f860 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f870 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
2f880 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2f890 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2f8a0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2f8b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2f8c0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2f8d0 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
2f8e0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2f8f0 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
2f900 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2f910 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
2f920 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2f930 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2f940 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2f950 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2f960 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2f970 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f980 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
2f990 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2f9a0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2f9b0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2f9c0 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
2f9d0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2f9e0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2f9f0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2fa00 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2fa10 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2fa20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2fa30 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
2fa40 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
2fa50 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2fa60 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2fa70 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2fa80 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
2fa90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2faa0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
2fab0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2fac0 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
2fad0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
2fae0 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
2faf0 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
2fb00 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2fb10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fb20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2fb30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2fb40 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
2fb50 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
2fb60 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
2fb70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2fb80 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
2fb90 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
2fba0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2fbb0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
2fbc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2fbd0 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
2fbe0 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
2fbf0 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
2fc00 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
2fc10 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
2fc20 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
2fc30 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
2fc40 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2fc50 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
2fc60 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2fc70 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2fc80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2fc90 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2fca0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
2fcb0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2fcc0 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
2fcd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2fce0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
2fcf0 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
2fd00 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
2fd10 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
2fd20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
2fd30 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
2fd40 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
2fd50 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2fd60 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
2fd70 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2fd80 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2fd90 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
2fda0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
2fdb0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
2fdc0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
2fdd0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
2fde0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
2fdf0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2fe00 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2fe10 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
2fe20 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2fe30 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2fe40 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2fe50 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
2fe60 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
2fe70 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
2fe80 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
2fe90 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
2fea0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
2feb0 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
2fec0 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
2fed0 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
2fee0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2fef0 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
2ff00 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
2ff10 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
2ff20 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
2ff30 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
2ff40 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
2ff50 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
2ff60 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
2ff70 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
2ff80 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
2ff90 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
2ffa0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
2ffb0 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
2ffc0 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
2ffd0 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
2ffe0 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
2fff0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
30000 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
30010 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
30020 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
30030 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
30040 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
30050 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
30060 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
30070 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
30080 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
30090 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
300a0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
300b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
300c0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
300d0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
300e0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
300f0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
30100 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
30110 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
30120 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
30130 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
30140 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
30150 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
30160 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
30170 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
30180 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
30190 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
301a0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
301b0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
301c0 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
301d0 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
301e0 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
301f0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
30200 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
30210 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
30220 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
30230 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
30240 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
30250 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
30260 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
30270 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
30280 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
30290 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
302a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
302b0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
302c0 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
302d0 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
302e0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
302f0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
30300 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
30310 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
30320 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
30330 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
30340 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
30350 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
30360 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
30370 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
30380 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
30390 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
303a0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
303b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
303c0 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
303d0 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
303e0 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
303f0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
30400 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
30410 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
30420 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
30430 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
30440 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
30450 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
30460 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
30470 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
30480 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
30490 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
304a0 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
304b0 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
304c0 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
304d0 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
304e0 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
304f0 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
30500 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
30510 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
30520 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
30530 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
30540 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
30550 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
30560 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
30570 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
30580 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
30590 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
305a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
305b0 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
305c0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
305d0 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
305e0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
305f0 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
30600 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
30610 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
30620 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
30630 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
30640 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
30650 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
30660 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
30670 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
30680 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
30690 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
306a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
306b0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
306c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
306d0 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
306e0 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
306f0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
30700 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
30710 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
30720 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
30730 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30740 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
30750 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
30760 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
30770 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
30780 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
30790 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
307a0 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
307b0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
307c0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
307d0 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
307e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
307f0 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
30800 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30810 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
30820 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
30830 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
30840 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
30850 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
30860 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
30870 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
30880 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
30890 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
308a0 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
308b0 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
308c0 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
308d0 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
308e0 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
308f0 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
30900 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
30910 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
30920 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
30930 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
30940 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
30950 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
30960 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
30970 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
30980 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
30990 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
309a0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
309b0 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
309c0 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
309d0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
309e0 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
309f0 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
30a00 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
30a10 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
30a20 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
30a30 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
30a40 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
30a50 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
30a60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30a70 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
30a80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30a90 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
30aa0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
30ab0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
30ac0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
30ad0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
30ae0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
30af0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
30b00 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
30b10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
30b20 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
30b30 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
30b40 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
30b50 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
30b60 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
30b70 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
30b80 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
30b90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
30ba0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
30bb0 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
30bc0 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
30bd0 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
30be0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
30bf0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
30c00 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
30c10 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
30c20 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
30c30 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
30c40 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
30c50 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
30c60 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
30c70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
30c80 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
30c90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
30ca0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
30cb0 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
30cc0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
30cd0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
30ce0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
30cf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30d00 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
30d10 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
30d20 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
30d30 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
30d40 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
30d50 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
30d60 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
30d70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
30d80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30d90 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
30da0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
30db0 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
30dc0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
30dd0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
30de0 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
30df0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
30e00 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
30e10 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
30e20 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
30e30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
30e40 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
30e50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30e60 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
30e70 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
30e80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
30e90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
30ea0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
30eb0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
30ec0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
30ed0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
30ee0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
30ef0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
30f00 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
30f10 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
30f20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
30f30 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
30f40 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
30f50 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
30f60 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
30f70 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
30f80 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
30f90 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
30fa0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
30fb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
30fc0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
30fd0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
30fe0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30ff0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
31000 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
31010 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
31020 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31030 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
31040 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
31050 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
31060 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31070 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  l);.SQLITE_API d
31080 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
31090 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
310a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
310b0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
310c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
310d0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
310e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
310f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
31100 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
31110 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
31120 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31130 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
31140 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
31150 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
31160 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
31170 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31180 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
31190 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
311a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
311b0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
311c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
311d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
311e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
311f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31200 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
31210 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76  TE_API sqlite3_v
31220 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
31230 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
31240 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31250 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
31260 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
31270 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
31280 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
31290 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
312a0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
312b0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
312c0 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
312d0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
312e0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
312f0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
31300 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
31310 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
31320 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
31330 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
31340 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
31350 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
31360 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
31370 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
31380 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
31390 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
313a0 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
313b0 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
313c0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
313d0 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
313e0 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
313f0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
31400 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
31410 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
31420 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
31430 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
31440 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
31450 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
31460 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
31470 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
31480 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
31490 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
314a0 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
314b0 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
314c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
314d0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
314e0 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
314f0 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
31500 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
31510 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
31520 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
31530 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
31540 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
31550 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
31560 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
31570 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
31580 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
31590 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
315a0 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
315b0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
315c0 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
315d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
315e0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
315f0 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
31600 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
31610 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
31620 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
31630 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
31640 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
31650 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
31660 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
31670 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
31680 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
31690 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
316a0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
316b0 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
316c0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
316d0 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
316e0 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
316f0 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
31700 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
31710 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
31720 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
31730 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
31740 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
31750 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
31760 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
31770 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
31780 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
31790 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
317a0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
317b0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
317c0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
317d0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
317e0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
317f0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
31800 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
31810 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
31820 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
31830 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
31840 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
31850 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
31860 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
31870 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
31880 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
31890 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
318a0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
318b0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
318c0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
318d0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
318e0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
318f0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
31900 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31910 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
31920 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
31930 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
31940 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
31950 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
31960 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
31970 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
31980 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31990 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
319a0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
319b0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
319c0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
319d0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
319e0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
319f0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
31a00 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
31a10 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
31a20 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
31a30 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
31a40 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
31a50 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
31a60 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
31a70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
31a80 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
31a90 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
31aa0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
31ab0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
31ac0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
31ad0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
31ae0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
31af0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
31b00 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
31b10 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
31b20 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
31b30 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
31b40 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
31b50 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
31b60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
31b70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
31b80 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
31b90 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
31ba0 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
31bb0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
31bc0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
31bd0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
31be0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
31bf0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
31c00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31c10 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
31c20 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
31c30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31c40 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
31c50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
31c60 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
31c70 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
31c80 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
31c90 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
31ca0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
31cb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
31cc0 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
31cd0 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
31ce0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
31cf0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
31d00 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
31d10 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
31d20 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
31d30 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
31d40 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
31d50 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
31d60 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
31d70 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
31d80 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
31d90 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
31da0 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
31db0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
31dc0 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
31dd0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
31de0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
31df0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
31e00 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
31e10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
31e20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
31e30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
31e40 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
31e50 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
31e60 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
31e70 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
31e80 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
31e90 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
31ea0 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
31eb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31ec0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
31ed0 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
31ee0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
31ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
31f00 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
31f10 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
31f20 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
31f30 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
31f40 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
31f50 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
31f60 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
31f70 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
31f80 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
31f90 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
31fa0 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
31fb0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
31fc0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
31fd0 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
31fe0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
31ff0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
32000 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
32010 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
32020 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
32030 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
32040 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
32050 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
32060 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
32070 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
32080 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
32090 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
320a0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
320b0 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
320c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
320d0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
320e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
320f0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
32100 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
32110 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
32120 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
32130 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
32140 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
32150 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
32160 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
32170 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
32180 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
32190 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
321a0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
321b0 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
321c0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
321d0 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
321e0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
321f0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
32200 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
32210 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
32220 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
32230 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
32240 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
32250 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
32260 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
32270 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
32280 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
32290 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
322a0 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63    Every SQL func
322b0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
322c0 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65  ion must be able
322d0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
322e0 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
322f0 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
32300 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
32310 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
32320 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
32330 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
32340 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
32350 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  .  ^An applicati
32360 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65  on may.** invoke
32370 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32380 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
32390 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
323a0 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
323b0 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
323c0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
323d0 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
323e0 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
323f0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68  eTextRep..** ^Wh
32400 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
32410 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
32420 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
32430 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
32440 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
32450 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
32460 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
32470 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
32480 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
32490 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
324a0 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
324b0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
324c0 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
324d0 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f  hat text.** enco
324e0 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
324f0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
32500 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
32510 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a   [SQLITE_ANY]..*
32520 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
32530 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
32540 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
32550 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
32560 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
32570 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
32580 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
32590 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
325a0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
325b0 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
325c0 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
325d0 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
325e0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
325f0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
32600 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
32610 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
32620 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
32630 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
32640 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
32650 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
32660 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
32670 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
32680 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
32690 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
326a0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
326b0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
326c0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
326d0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
326e0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
326f0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
32700 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
32710 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
32720 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
32730 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
32740 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
32750 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
32760 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
32770 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
32780 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
32790 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
327a0 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
327b0 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
327c0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
327d0 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
327e0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
327f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
32800 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32810 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
32820 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
32830 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
32840 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32850 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
32860 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
32870 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
32880 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
32890 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
328a0 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
328b0 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
328c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
328d0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
328e0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
328f0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
32900 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
32910 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
32920 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
32930 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
32940 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
32950 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
32960 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
32970 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
32980 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
32990 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
329a0 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
329b0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
329c0 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
329d0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
329e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
329f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
32a00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
32a10 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
32a20 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
32a30 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
32a40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
32a50 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
32a60 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
32a70 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
32a80 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
32a90 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
32aa0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
32ab0 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
32ac0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
32ad0 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
32ae0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
32af0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
32b00 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
32b10 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
32b20 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
32b30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
32b40 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
32b50 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
32b60 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
32b70 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
32b80 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
32b90 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
32ba0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
32bb0 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
32bc0 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
32bd0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
32be0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
32bf0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
32c00 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
32c10 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
32c20 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
32c30 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
32c40 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
32c50 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
32c60 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
32c70 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
32c80 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
32c90 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
32ca0 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
32cb0 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
32cc0 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
32cd0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
32ce0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
32cf0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
32d00 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
32d10 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
32d20 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
32d30 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
32d40 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
32d50 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32d60 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
32d70 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
32d80 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
32d90 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
32da0 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
32db0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
32dc0 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
32dd0 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
32de0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
32df0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
32e00 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
32e10 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
32e20 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
32e30 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
32e40 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
32e50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
32e60 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
32e70 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
32e80 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
32e90 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
32ea0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
32eb0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
32ec0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
32ed0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
32ee0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32ef0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
32f00 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
32f10 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
32f20 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
32f30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
32f40 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
32f50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32f60 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
32f70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
32f80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
32f90 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
32fa0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
32fb0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
32fc0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
32fd0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
32fe0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
32ff0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
33000 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
33010 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
33020 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
33030 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
33040 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
33050 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
33060 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
33070 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  text*).);.SQLITE
33080 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
33090 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
330a0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
330b0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
330c0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
330d0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
330e0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
330f0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
33100 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
33110 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33120 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33130 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
33140 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
33150 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
33160 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
33170 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
33180 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
33190 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
331a0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
331b0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
331c0 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
331d0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
331e0 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
331f0 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
33200 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
33210 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
33220 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
33230 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
33240 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
33250 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
33260 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
33270 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
33280 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
33290 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
332a0 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
332b0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
332c0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
332d0 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
332e0 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
332f0 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
33300 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33310 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
33320 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
33330 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
33340 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
33350 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
33360 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
33370 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
33380 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
33390 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
333a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
333b0 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
333c0 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
333d0 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
333e0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
333f0 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
33400 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
33410 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
33420 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
33430 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
33440 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
33450 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
33460 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
33470 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
33480 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
33490 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
334a0 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
334b0 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
334c0 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
334d0 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
334e0 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
334f0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
33500 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
33510 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
33520 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
33530 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
33540 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
33550 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
33560 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
33570 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
33580 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
33590 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
335a0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
335b0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
335c0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
335d0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
335e0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  stmt*);.SQLITE_A
335f0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
33600 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
33610 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
33620 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
33630 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
33640 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
33650 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
33660 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
33670 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
33680 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
33690 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
336a0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
336b0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
336c0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
336d0 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
336e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
336f0 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
33700 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
33710 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
33720 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
33730 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
33740 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
33750 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
33760 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
33770 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
33780 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
33790 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
337a0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
337b0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
337c0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
337d0 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
337e0 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
337f0 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
33800 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
33810 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33820 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
33830 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33840 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
33850 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
33860 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
33870 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
33880 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
33890 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
338a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
338b0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
338c0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
338d0 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
338e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
338f0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
33900 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
33910 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
33920 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
33930 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
33940 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
33950 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
33960 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
33970 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
33980 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
33990 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
339a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
339b0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
339c0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
339d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
339e0 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
339f0 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
33a00 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
33a10 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
33a20 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
33a30 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
33a40 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
33a50 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
33a60 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
33a70 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
33a80 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
33a90 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
33aa0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
33ab0 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
33ac0 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
33ad0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
33ae0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33af0 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
33b00 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
33b10 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
33b20 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
33b30 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
33b40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33b50 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33b60 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
33b70 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
33b80 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
33b90 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
33ba0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
33bb0 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
33bc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33bd0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
33be0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33bf0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
33c00 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
33c10 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
33c20 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
33c30 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
33c40 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
33c50 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
33c60 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
33c70 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
33c80 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
33c90 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
33ca0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
33cb0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
33cc0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
33cd0 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
33ce0 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
33cf0 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
33d00 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
33d10 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
33d20 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
33d30 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
33d40 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
33d50 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
33d60 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
33d70 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
33d80 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
33d90 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
33da0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
33db0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
33dc0 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
33dd0 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
33de0 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
33df0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
33e00 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
33e10 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
33e20 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
33e30 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
33e40 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
33e50 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
33e60 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
33e70 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
33e80 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
33e90 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
33ea0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
33eb0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
33ec0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
33ed0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
33ee0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
33ef0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
33f00 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
33f10 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
33f20 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
33f30 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
33f40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
33f50 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
33f60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
33f70 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
33f80 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
33f90 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
33fa0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
33fb0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
33fc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
33fd0 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c  rameters..*/.SQL
33fe0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
33ff0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
34000 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
34010 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
34020 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
34030 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
34040 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
34050 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
34060 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
34070 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34080 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
34090 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
340a0 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
340b0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
340c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
340d0 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
340e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
340f0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
34100 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
34110 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
34120 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
34130 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
34140 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
34150 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
34160 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
34170 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
34180 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
34190 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
341a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
341b0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
341c0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
341d0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
341e0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
341f0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
34200 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
34210 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
34220 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
34230 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34240 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
34250 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
34260 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
34270 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
34280 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
34290 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
342a0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
342b0 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
342c0 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
342d0 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
342e0 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
342f0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
34300 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
34310 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
34320 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
34330 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
34340 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
34350 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
34360 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
34370 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
34380 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
34390 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
343a0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
343b0 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
343c0 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
343d0 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
343e0 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
343f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
34400 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
34410 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
34420 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
34430 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
34440 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
34450 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
34460 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
34470 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
34480 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
34490 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
344a0 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
344b0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
344c0 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
344d0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
344e0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
344f0 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
34500 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
34510 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
34520 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
34530 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
34540 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
34550 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
34560 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
34570 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
34580 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
34590 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
345a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
345b0 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
345c0 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
345d0 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
345e0 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
345f0 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
34600 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
34610 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
34620 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
34630 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
34640 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
34650 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34660 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
34670 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
34680 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
34690 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69  L pointer if N i
346a0 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f  s.** less than o
346b0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
346c0 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  or if a memory a
346d0 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
346e0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
346f0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
34700 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
34710 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34720 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
34730 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
34740 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
34750 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
34760 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
34770 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
34780 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
34790 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
347a0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
347b0 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
347c0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
347d0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
347e0 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
347f0 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
34800 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
34810 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  n.)^.**.** ^SQLi
34820 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
34830 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
34840 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
34850 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
34860 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
34870 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
34880 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
34890 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
348a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
348b0 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
348c0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
348d0 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
348e0 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
348f0 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
34900 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
34910 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
34920 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
34930 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
34940 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
34950 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
34960 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
34970 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
34980 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
34990 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
349a0 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
349b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
349c0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
349d0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
349e0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
349f0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
34a00 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
34a10 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
34a20 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
34a30 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
34a40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34a50 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
34a60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
34a70 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
34a80 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
34a90 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
34aa0 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
34ab0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
34ac0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
34ad0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34ae0 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
34af0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
34b00 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
34b10 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
34b20 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
34b30 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
34b40 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
34b50 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
34b60 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
34b70 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
34b80 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
34b90 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
34ba0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34bb0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
34bc0 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
34bd0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
34be0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
34bf0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
34c00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
34c10 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
34c20 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
34c30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34c40 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
34c50 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
34c60 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
34c70 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
34c80 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
34c90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
34ca0 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
34cb0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
34cc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
34cd0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
34ce0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
34cf0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
34d00 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
34d10 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
34d20 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
34d30 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
34d40 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ction..*/.SQLITE
34d50 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71  _API sqlite3 *sq
34d60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
34d70 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
34d80 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
34d90 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
34da0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
34db0 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ata.**.** The fo
34dc0 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
34dd0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
34de0 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
34df0 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
34e00 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
34e10 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
34e20 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
34e30 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
34e40 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
34e50 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
34e60 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
34e70 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
34e80 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
34e90 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
34ea0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
34eb0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
34ec0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
34ed0 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
34ee0 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
34ef0 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
34f00 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
34f10 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
34f20 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
34f30 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
34f40 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
34f50 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
34f60 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
34f70 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
34f80 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
34f90 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
34fa0 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
34fb0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
34fc0 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
34fd0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
34fe0 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
34ff0 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
35000 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
35010 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
35020 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
35030 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
35040 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
35050 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
35060 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
35070 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
35080 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35090 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
350a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
350b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
350c0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
350d0 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
350e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
350f0 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
35100 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
35110 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
35120 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35130 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35140 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61  n. ^If no metada
35150 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72  ta has been ever
35160 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72  .** been set for
35170 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
35180 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  t of the functio
35190 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72  n, or if the cor
351a0 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75  responding.** fu
351b0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
351c0 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e   has changed sin
351d0 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  ce the meta-data
351e0 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65   was set,.** the
351f0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  n sqlite3_get_au
35200 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20  xdata() returns 
35210 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
35220 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35230 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
35240 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
35250 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
35260 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69   pointed to by i
35270 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
35280 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   as the metadata
35290 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
352a0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
352b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
352c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
352d0 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
352e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
352f0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
35300 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
35310 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
35320 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
35330 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  oyed..** ^If it 
35340 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
35350 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
35360 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
35370 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
35380 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
35390 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
353a0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
353b0 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74  n.** the metadat
353c0 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  a when the corre
353d0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
353e0 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
353f0 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ges.** or when t
35400 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
35410 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63   completes, whic
35420 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
35430 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
35440 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20  is free to call 
35450 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61  the destructor a
35460 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61  nd drop metadata
35470 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d   on any.** param
35480 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63  eter of any func
35490 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65  tion at any time
354a0 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61  .  ^The only gua
354b0 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a  rantee is that.*
354c0 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  * the destructor
354d0 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
354e0 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
354f0 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a  ata is dropped..
35500 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
35510 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
35520 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
35530 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
35540 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
35550 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
35560 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
35570 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
35580 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
35590 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
355a0 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a  ameters].)^.**.*
355b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
355c0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
355d0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
355e0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
355f0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
35600 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
35610 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
35620 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
35630 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
35640 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
35650 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
35660 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
35670 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
35680 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
35690 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
356a0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
356b0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
356c0 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
356d0 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
356e0 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
356f0 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
35700 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
35710 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
35720 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
35730 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
35740 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
35750 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
35760 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
35770 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
35780 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
35790 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
357a0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
357b0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
357c0 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
357d0 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
357e0 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
357f0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
35800 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
35810 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
35820 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
35830 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
35840 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
35850 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
35860 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
35870 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
35880 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
35890 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
358a0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
358b0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
358c0 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
358d0 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
358e0 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
358f0 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
35900 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
35910 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
35920 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
35930 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
35940 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
35950 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
35960 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
35970 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
35980 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
35990 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
359a0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
359b0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
359c0 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
359d0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
359e0 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
359f0 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
35a00 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
35a10 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
35a20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
35a30 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
35a40 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
35a50 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
35a60 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
35a70 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
35a80 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35a90 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
35aa0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35ab0 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
35ac0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
35ad0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
35ae0 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
35af0 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
35b00 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
35b10 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
35b20 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
35b30 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
35b40 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
35b50 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
35b60 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
35b70 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
35b80 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
35b90 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
35ba0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
35bb0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
35bc0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35bd0 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
35be0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
35bf0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
35c00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35c10 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35c20 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
35c30 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
35c40 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
35c50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
35c60 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
35c70 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
35c80 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
35c90 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
35ca0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35cb0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
35cc0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
35cd0 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
35ce0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
35cf0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35d00 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
35d10 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
35d20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
35d30 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
35d40 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
35d50 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
35d60 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
35d70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35d80 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
35d90 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
35da0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
35db0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
35dc0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35dd0 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
35de0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
35df0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
35e00 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
35e10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35e20 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35e30 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
35e40 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
35e50 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
35e60 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
35e70 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
35e80 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
35e90 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
35ea0 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
35eb0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
35ec0 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
35ed0 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
35ee0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
35ef0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
35f00 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
35f10 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
35f20 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
35f30 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
35f40 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
35f50 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
35f60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
35f70 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
35f80 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
35f90 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
35fa0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
35fb0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35fc0 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
35fd0 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
35fe0 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
35ff0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
36000 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
36010 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
36020 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36030 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
36040 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
36050 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
36060 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
36070 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
36080 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
36090 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
360a0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
360b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
360c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
360d0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
360e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
360f0 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
36100 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
36110 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
36120 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
36130 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
36140 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
36150 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
36160 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
36170 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36180 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
36190 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
361a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
361b0 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
361c0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
361d0 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
361e0 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
361f0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
36200 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
36210 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
36220 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
36230 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
36240 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
36250 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
36260 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36270 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
36280 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
36290 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
362a0 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
362b0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
362c0 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
362d0 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
362e0 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
362f0 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
36300 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
36310 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
36320 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36330 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
36340 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36350 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
36360 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
36370 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
36380 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36390 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
363a0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
363b0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
363c0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
363d0 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
363e0 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
363f0 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
36400 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
36410 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
36420 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
36430 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
36440 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
36450 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
36460 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
36470 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
36480 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36490 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
364a0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
364b0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
364c0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
364d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
364e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
364f0 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
36500 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
36510 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
36520 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
36530 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36540 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
36550 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
36560 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
36570 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36580 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36590 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
365a0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
365b0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
365c0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
365d0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
365e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
365f0 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
36600 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
36610 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
36620 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36630 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
36640 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
36650 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36660 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
36670 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
36680 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
36690 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
366a0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
366b0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
366c0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
366d0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
366e0 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
366f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36700 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
36710 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
36720 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
36730 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
36740 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
36750 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
36760 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
36770 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
36780 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
36790 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  ly..** ^SQLite t
367a0 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
367b0 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
367c0 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
367d0 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
367e0 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
367f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
36800 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
36810 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
36820 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
36830 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
36840 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
36850 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
36860 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
36870 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
36880 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
36890 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
368a0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
368b0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
368c0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
368d0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
368e0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
368f0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
36900 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
36910 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
36920 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
36930 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
36940 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
36950 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
36960 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
36970 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
36980 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
36990 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72  sult.  If the 3r
369a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
369b0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
369c0 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20  n it.** must be 
369d0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20  the byte offset 
369e0 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20  into the string 
369f0 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
36a00 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a  rminator would.*
36a10 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20  * appear if the 
36a20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c  string where NUL
36a30 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
36a40 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
36a50 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ers occur.** in 
36a60 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20  the string at a 
36a70 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74  byte offset that
36a80 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68   is less than th
36a90 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33  e value of the 3
36aa0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  rd.** parameter,
36ab0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
36ac0 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  ing string will 
36ad0 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
36ae0 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a   NULs and the.**
36af0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
36b00 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67  ssions operating
36b10 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68   on strings with
36b20 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
36b30 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
36b40 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
36b50 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
36b60 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36b70 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
36b80 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
36b90 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
36ba0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
36bb0 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
36bc0 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
36bd0 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
36be0 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
36bf0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
36c00 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
36c10 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
36c20 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
36c30 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
36c40 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
36c50 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
36c60 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
36c70 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
36c80 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
36c90 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
36ca0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
36cb0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
36cc0 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
36cd0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
36ce0 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
36cf0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
36d00 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
36d10 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
36d20 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
36d30 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
36d40 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
36d50 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
36d60 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
36d70 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
36d80 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
36d90 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
36da0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
36db0 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
36dc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
36dd0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
36de0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
36df0 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
36e00 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
36e10 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
36e20 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
36e30 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
36e40 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
36e50 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
36e60 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
36e70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36e80 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
36e90 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
36ea0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
36eb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
36ec0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
36ed0 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
36ee0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
36ef0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36f00 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
36f10 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
36f20 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  eter.  ^The.** s
36f30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
36f40 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
36f50 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
36f60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
36f70 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
36f80 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
36f90 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
36fa0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
36fb0 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
36fc0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
36fd0 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
36fe0 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
36ff0 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
37000 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65  .** ^A [protecte
37010 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
37020 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
37030 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
37040 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
37050 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
37060 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
37070 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
37080 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
37090 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
370a0 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
370b0 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
370c0 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
370d0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
370e0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
370f0 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
37100 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
37110 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
37120 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
37130 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
37140 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
37150 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
37160 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
37170 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
37180 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
37190 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
371a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
371b0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
371c0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
371d0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
371e0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
371f0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
37200 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
37210 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37220 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49  *, double);.SQLI
37230 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
37240 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37250 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37260 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
37270 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
37280 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
37290 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
372a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
372b0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
372c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
372d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
372e0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
372f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
37300 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37310 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37320 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
37330 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
37340 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
37350 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37360 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
37370 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
37380 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37390 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
373a0 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
373b0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  ext*, int);.SQLI
373c0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
373d0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
373e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
373f0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
37400 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
37410 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37420 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
37430 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
37440 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
37450 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
37460 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37470 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
37480 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
37490 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
374a0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
374b0 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  t_text16(sqlite3
374c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
374d0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
374e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
374f0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
37500 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37510 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
37520 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
37530 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
37540 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
37550 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
37560 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
37570 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
37580 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
37590 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
375a0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
375b0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
375c0 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
375d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
375e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
375f0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
37600 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
37610 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
37620 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
37630 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37640 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
37650 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a  ating Sequences.
37660 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
37670 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f  ctions add, remo
37680 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20  ve, or modify a 
37690 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f  [collation] asso
376a0 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
376b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
376c0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
376d0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
376e0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
376f0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
37700 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20   collation is a 
37710 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
37720 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
37730 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
37740 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
37750 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
37760 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
37770 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
37780 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
37790 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
377a0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
377b0 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  * ^Collation nam
377c0 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20  es that compare 
377d0 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20  equal according 
377e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e  to [sqlite3_strn
377f0 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63  icmp()] are.** c
37800 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
37810 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a  the same name..*
37820 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64  *.** ^(The third
37830 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74   argument (eText
37840 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  Rep) must be one
37850 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
37860 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  s:.** <ul>.** <l
37870 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  i> [SQLITE_UTF8]
37880 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
37890 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c  E_UTF16LE],.** <
378a0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
378b0 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6BE],.** <li> [S
378c0 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72  QLITE_UTF16], or
378d0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
378e0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e  _UTF16_ALIGNED].
378f0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  .** </ul>)^.** ^
37900 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  The eTextRep arg
37910 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73  ument determines
37920 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
37930 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a   strings passed.
37940 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ** to the collat
37950 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
37960 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b  lback, xCallback
37970 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
37980 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51  E_UTF16] and [SQ
37990 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
379a0 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65  ED] values for e
379b0 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65  TextRep.** force
379c0 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55   strings to be U
379d0 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65  TF16 with native
379e0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
379f0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
37a00 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
37a10 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66  e for eTextRep f
37a20 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f  orces strings to
37a30 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20   begin.** on an 
37a40 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73  even byte addres
37a50 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  s..**.** ^The fo
37a60 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70  urth argument, p
37a70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69  Arg, is an appli
37a80 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
37a90 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
37aa0 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73  ed.** through as
37ab0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
37ac0 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ent to the colla
37ad0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
37ae0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
37af0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
37b00 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73  t, xCallback, is
37b10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
37b20 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
37b30 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70  tion..** ^Multip
37b40 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  le collating fun
37b50 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65  ctions can be re
37b60 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
37b70 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
37b80 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65  .** with differe
37b90 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61  nt eTextRep para
37ba0 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74  meters and SQLit
37bb0 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68  e will use which
37bc0 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ever.** function
37bd0 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
37be0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
37bf0 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f  ta transformatio
37c00 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43  n..** ^If the xC
37c10 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
37c20 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
37c30 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
37c40 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74  tion is.** delet
37c50 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63  ed.  ^When all c
37c60 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37c70 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61  ns having the sa
37c80 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65  me name are dele
37c90 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c  ted,.** that col
37ca0 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  lation is no lon
37cb0 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a  ger usable..**.*
37cc0 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  * ^The collating
37cd0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
37ce0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
37cf0 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  th a copy of the
37d00 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63   pArg .** applic
37d10 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
37d20 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20  er and with two 
37d30 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65  strings in the e
37d40 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
37d50 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78  d.** by the eTex
37d60 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20  tRep argument.  
37d70 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
37d80 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75  nction must retu
37d90 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  rn an.** integer
37da0 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76   that is negativ
37db0 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69  e, zero, or posi
37dc0 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66  tive.** if the f
37dd0 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
37de0 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20  ess than, equal 
37df0 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
37e00 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a  han the second,.
37e10 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
37e20 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75    A collating fu
37e30 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61  nction must alwa
37e40 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ys return the sa
37e50 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
37e60 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
37e70 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
37e80 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
37e90 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
37ea0 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
37eb0 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
37ec0 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
37ed0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
37ee0 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
37ef0 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
37f00 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
37f10 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
37f20 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
37f30 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
37f40 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37f50 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
37f60 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
37f70 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
37f80 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
37f90 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
37fa0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
37fb0 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
37fc0 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
37fd0 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
37fe0 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
37ff0 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
38000 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
38010 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
38020 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
38030 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
38040 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
38050 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
38060 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
38070 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
38080 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
38090 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
380a0 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
380b0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
380c0 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
380d0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
380e0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
380f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
38100 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
38110 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
38120 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
38130 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
38140 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
38150 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
38160 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
38170 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
38180 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
38190 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
381a0 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
381b0 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
381c0 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
381d0 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
381e0 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
381f0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
38200 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
38210 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
38220 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
38230 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
38240 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
38250 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
38260 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
38270 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
38280 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
38290 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
382a0 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
382b0 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
382c0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
382d0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
382e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
382f0 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
38300 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
38310 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
38320 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
38330 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
38340 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
38350 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
38360 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
38370 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
38380 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
38390 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
383a0 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
383b0 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
383c0 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
383d0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
383e0 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
383f0 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
38400 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
38410 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
38420 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
38430 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
38440 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
38450 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
38460 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
38470 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
38480 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
38490 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
384a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
384b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
384c0 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
384d0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
384e0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
384f0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
38500 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
38510 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
38520 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
38530 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
38540 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
38550 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
38560 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
38570 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
38580 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
38590 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
385a0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
385b0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
385c0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
385d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
385e0 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
385f0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
38600 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  oid*).);.SQLITE_
38610 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
38620 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
38630 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
38640 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
38650 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
38660 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
38670 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
38680 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
38690 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
386a0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
386b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
386c0 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65   Collation Neede
386d0 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  d Callbacks.**.*
386e0 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69  * ^To avoid havi
386f0 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ng to register a
38700 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ll collation seq
38710 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20  uences before a 
38720 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20  database.** can 
38730 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c  be used, a singl
38740 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
38750 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
38760 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a  tered with the.*
38770 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
38780 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e  ection] to be in
38790 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
387a0 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n und