System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 861397a5ff121000ad44a208efee2825d0189816:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 37 2e 31 36 2e 20 20  ersion 3.7.16.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e  atic.#endif.#ifn
0550: 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23  def SQLITE_API.#
0560: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41   define SQLITE_A
0570: 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a  PI.#endif./*****
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20  ********* Begin 
0590: 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68  file sqliteInt.h
05a0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20  ********/./*.** 
05d0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31  2001 September 1
05e0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  5.**.** The auth
05f0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70  or disclaims cop
0600: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73  yright to this s
0610: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20  ource code.  In 
0620: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65  place of.** a le
0630: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65  gal notice, here
0640: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a   is a blessing:.
0650: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  **.**    May you
0660: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74   do good and not
0670: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79   evil..**    May
0680: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76   you find forgiv
0690: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65  eness for yourse
06a0: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f  lf and forgive o
06b0: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79  thers..**    May
06c0: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c   you share freel
06d0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20  y, never taking 
06e0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69  more than you gi
06f0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ve..**.*********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0740: 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74  .** Internal int
0750: 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f  erface definitio
0760: 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a  ns for SQLite..*
0770: 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51  *.*/.#ifndef _SQ
0780: 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69  LITEINT_H_.#defi
0790: 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f  ne _SQLITEINT_H_
07a0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64  ../*.** These #d
07b0: 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e  efines should en
07c0: 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73  able >2GB file s
07d0: 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20  upport on POSIX 
07e0: 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  if the.** underl
07f0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
0800: 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69  ystem supports i
0810: 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61  t.  If the OS la
0820: 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c  cks.** large fil
0830: 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66  e support, or if
0840: 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f   the OS is windo
0850: 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64  ws, these should
0860: 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   be no-ops..**.*
0870: 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20  * Ticket #2739: 
0880: 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f   The _LARGEFILE_
0890: 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73  SOURCE macro mus
08a0: 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20  t appear before 
08b0: 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69  any.** system #i
08c0: 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c  ncludes.  Hence,
08d0: 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63   this block of c
08e0: 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20  ode must be the 
08f0: 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f  very first.** co
0900: 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65  de in all source
0910: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61   files..**.** La
0920: 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74  rge file support
0930: 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64   can be disabled
0940: 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c   using the -DSQL
0950: 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20  ITE_DISABLE_LFS 
0960: 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65  switch.** on the
0970: 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e   compiler comman
0980: 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73  d line.  This is
0990: 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f   necessary if yo
09a0: 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a  u are compiling.
09b0: 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d  ** on a recent m
09c0: 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20  achine (ex: Red 
09d0: 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75  Hat 7.2) but you
09e0: 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20   want your code 
09f0: 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e  to work.** on an
0a00: 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28   older machine (
0a10: 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29  ex: Red Hat 6.0)
0a20: 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c  .  If you compil
0a30: 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32  e on Red Hat 7.2
0a40: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73  .** without this
0a50: 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20   option, LFS is 
0a60: 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53  enable.  But LFS
0a70: 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20   does not exist 
0a80: 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a  in the kernel.**
0a90: 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c   in Red Hat 6.0,
0aa0: 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e   so the code won
0ab0: 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c  't work.  Hence,
0ac0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e   for maximum bin
0ad0: 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69  ary.** portabili
0ae0: 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d  ty you should om
0af0: 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 69  it LFS..**.** Si
0b00: 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f  milar is true fo
0b10: 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53  r Mac OS X.  LFS
0b20: 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74   is only support
0b30: 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39  ed on Mac OS X 9
0b40: 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23   and later..*/.#
0b50: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49  ifndef SQLITE_DI
0b60: 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69  SABLE_LFS.# defi
0b70: 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20  ne _LARGE_FILE  
0b80: 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20       1.# ifndef 
0b90: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54  _FILE_OFFSET_BIT
0ba0: 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49  S.#   define _FI
0bb0: 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36  LE_OFFSET_BITS 6
0bc0: 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69  4.# endif.# defi
0bd0: 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f  ne _LARGEFILE_SO
0be0: 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f  URCE 1.#endif../
0bf0: 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65  *.** Include the
0c00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 68   configuration h
0c10: 65 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 20  eader output by 
0c20: 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 77  'configure' if w
0c30: 65 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  e're using the.*
0c40: 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 64  * autoconf-based
0c50: 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 66   build.*/.#ifdef
0c60: 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 4f   _HAVE_SQLITE_CO
0c70: 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 20  NFIG_H.#include 
0c80: 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 69  "config.h".#endi
0c90: 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  f../************
0ca0: 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74  ** Include sqlit
0cb0: 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 20  eLimit.h in the 
0cc0: 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65  middle of sqlite
0cd0: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  Int.h **********
0ce0: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
0cf0: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71  ** Begin file sq
0d00: 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a  liteLimit.h ****
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d30: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d 61  */./*.** 2007 Ma
0d40: 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  y 7.**.** The au
0d50: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
0d60: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
0d70: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
0d80: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0d90: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0da0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0db0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0dc0: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0dd0: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0de0: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0df0: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0e00: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0e10: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0e20: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
0e30: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
0e40: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
0e50: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ea0: 2a 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 66  **.** .** This f
0eb0: 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 69  ile defines vari
0ec0: 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 68  ous limits of wh
0ed0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 72  at SQLite can pr
0ee0: 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ocess..*/../*.**
0ef0: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   The maximum len
0f00: 67 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f 72  gth of a TEXT or
0f10: 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 20   BLOB in bytes. 
0f20: 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 6c    This also.** l
0f30: 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f  imits the size o
0f40: 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 62  f a row in a tab
0f50: 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a 0a  le or index..**.
0f60: 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d 69  ** The hard limi
0f70: 74 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 79  t is the ability
0f80: 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
0f90: 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 74  ned integer.** t
0fa0: 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a 65  o count the size
0fb0: 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 37  : 2^31-1 or 2147
0fc0: 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 64  483647..*/.#ifnd
0fd0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  ef SQLITE_MAX_LE
0fe0: 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51  NGTH.# define SQ
0ff0: 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 20  LITE_MAX_LENGTH 
1000: 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 69  1000000000.#endi
1010: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 73  f../*.** This is
1020: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1030: 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 20  ber of.**.**    
1040: 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  * Columns in a t
1050: 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c  able.**    * Col
1060: 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
1070: 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e 73  .**    * Columns
1080: 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 20   in a view.**   
1090: 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20   * Terms in the 
10a0: 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 6e  SET clause of an
10b0: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
10c0: 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20  t.**    * Terms 
10d0: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
10e0: 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
10f0: 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a 20  atement.**    * 
1100: 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 4f  Terms in the GRO
1110: 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 42  UP BY or ORDER B
1120: 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 53  Y clauses of a S
1130: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1140: 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69  .**    * Terms i
1150: 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61  n the VALUES cla
1160: 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54  use of an INSERT
1170: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
1180: 20 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20   The hard upper 
1190: 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 32  limit here is 32
11a0: 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 62  676.  Most datab
11b0: 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c 0a  ase people will.
11c0: 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 74  ** tell you that
11d0: 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d 61   in a well-norma
11e0: 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c 20  lized database, 
11f0: 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f 75  you usually shou
1200: 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 6d  ld.** not have m
1210: 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 6e  ore than a dozen
1220: 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 69   or so columns i
1230: 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 6e  n any table.  An
1240: 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 20  d if.** that is 
1250: 74 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 20  the case, there 
1260: 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 68  is no point in h
1270: 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aving more than 
1280: 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 76  a few.** dozen v
1290: 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 20  alues in any of 
12a0: 74 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 74  the other situat
12b0: 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61  ions described a
12c0: 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  bove..*/.#ifndef
12d0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55   SQLITE_MAX_COLU
12e0: 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  MN.# define SQLI
12f0: 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 30  TE_MAX_COLUMN 20
1300: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1310: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   The maximum len
1320: 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  gth of a single 
1330: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1340: 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 74   bytes..**.** It
1350: 20 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20   used to be the 
1360: 63 61 73 65 20 74 68 61 74 20 73 65 74 74 69 6e  case that settin
1370: 67 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f 20  g this value to 
1380: 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 75  zero would.** tu
1390: 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 66  rn the limit off
13a0: 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c 6f  .  That is no lo
13b0: 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 69  nger true.  It i
13c0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a 2a  s not possible.*
13d0: 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 6c  * to turn this l
13e0: 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 66  imit off..*/.#if
13f0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1400: 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 66  SQL_LENGTH.# def
1410: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53  ine SQLITE_MAX_S
1420: 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 30  QL_LENGTH 100000
1430: 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  0000.#endif../*.
1440: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  ** The maximum d
1450: 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 65  epth of an expre
1460: 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 73  ssion tree. This
1470: 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 0a   is limited to .
1480: 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62  ** some extent b
1490: 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c  y SQLITE_MAX_SQL
14a0: 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f 6d  _LENGTH. But som
14b0: 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 20  etime you might 
14c0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 63  .** want to plac
14d0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c 69  e more severe li
14e0: 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  mits on the comp
14f0: 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a 2a  lexity of an .**
1500: 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a 0a   expression..**.
1510: 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20  ** A value of 0 
1520: 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 61  used to mean tha
1530: 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
1540: 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a 2a  not enforced..**
1550: 20 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f 20   But that is no 
1560: 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 68  longer true.  Th
1570: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 73  e limit is now s
1580: 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 64  trictly enforced
1590: 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 73  .** at all times
15a0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
15b0: 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50  ITE_MAX_EXPR_DEP
15c0: 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  TH.# define SQLI
15d0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54  TE_MAX_EXPR_DEPT
15e0: 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f  H 1000.#endif../
15f0: 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d  *.** The maximum
1600: 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
1610: 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
1620: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1630: 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 6e  .** The code gen
1640: 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 6f  erator for compo
1650: 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1660: 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a 2a  ments does one.*
1670: 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 72  * level of recur
1680: 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 65  sion for each te
1690: 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 65  rm.  A stack ove
16a0: 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c 74  rflow can result
16b0: 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 65  .** if the numbe
16c0: 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 6f  r of terms is to
16d0: 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 61  o large.  In pra
16e0: 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c 0a  ctice, most SQL.
16f0: 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f 72  ** never has mor
1700: 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 65  e than 3 or 4 te
1710: 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c 75  rms.  Use a valu
1720: 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 6c  e of 0 to disabl
1730: 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 6f  e.** any limit o
1740: 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
1750: 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1760: 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a 23  unt SELECT..*/.#
1770: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41  ifndef SQLITE_MA
1780: 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  X_COMPOUND_SELEC
1790: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  T.# define SQLIT
17a0: 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53  E_MAX_COMPOUND_S
17b0: 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 66  ELECT 500.#endif
17c0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69  ../*.** The maxi
17d0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70  mum number of op
17e0: 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 20  codes in a VDBE 
17f0: 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 20  program..** Not 
1800: 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 63  currently enforc
1810: 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  ed..*/.#ifndef S
1820: 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f  QLITE_MAX_VDBE_O
1830: 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  P.# define SQLIT
1840: 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 35  E_MAX_VDBE_OP 25
1850: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  000.#endif../*.*
1860: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  * The maximum nu
1870: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
1880: 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e 63  s to an SQL func
1890: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  tion..*/.#ifndef
18a0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43   SQLITE_MAX_FUNC
18b0: 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 6e  TION_ARG.# defin
18c0: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e  e SQLITE_MAX_FUN
18d0: 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 65  CTION_ARG 127.#e
18e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  ndif../*.** The 
18f0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1900: 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 65  f in-memory page
1910: 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65  s to use for the
1920: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a 2a   main database.*
1930: 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 20  * table and for 
1940: 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 73  temporary tables
1950: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45  .  The SQLITE_DE
1960: 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45  FAULT_CACHE_SIZE
1970: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
1980: 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 45  TE_DEFAULT_CACHE
1990: 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53  _SIZE.# define S
19a0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41  QLITE_DEFAULT_CA
19b0: 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a 23  CHE_SIZE  2000.#
19c0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
19d0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 4d  LITE_DEFAULT_TEM
19e0: 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 64  P_CACHE_SIZE.# d
19f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
1a00: 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 5f  AULT_TEMP_CACHE_
1a10: 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 66  SIZE  500.#endif
1a20: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ../*.** The defa
1a30: 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 72  ult number of fr
1a40: 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c 61  ames to accumula
1a50: 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69  te in the log fi
1a60: 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 65  le before.** che
1a70: 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 64  ckpointing the d
1a80: 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d  atabase in WAL m
1a90: 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ode..*/.#ifndef 
1aa0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57  SQLITE_DEFAULT_W
1ab0: 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e  AL_AUTOCHECKPOIN
1ac0: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  T.# define SQLIT
1ad0: 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55  E_DEFAULT_WAL_AU
1ae0: 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 30  TOCHECKPOINT  10
1af0: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1b00: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   The maximum num
1b10: 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20  ber of attached 
1b20: 64 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 73  databases.  This
1b30: 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
1b40: 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 54   0.** and 62.  T
1b50: 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  he upper bound o
1b60: 6e 20 36 32 20 69 73 20 62 65 63 61 75 73 65 20  n 62 is because 
1b70: 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  a 64-bit integer
1b80: 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 73   bitmap.** is us
1b90: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
1ba0: 20 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 20   track attached 
1bb0: 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 69  databases..*/.#i
1bc0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1bd0: 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 69  _ATTACHED.# defi
1be0: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54  ne SQLITE_MAX_AT
1bf0: 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 66  TACHED 10.#endif
1c00: 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78  .../*.** The max
1c10: 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 20  imum value of a 
1c20: 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 68  ?nnn wildcard th
1c30: 61 74 20 74 68 65 20 70 61 72 73 65 72 20 77 69  at the parser wi
1c40: 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 69  ll accept..*/.#i
1c50: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1c60: 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1c70: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1c80: 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
1c90: 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 0a  MBER 999.#endif.
1ca0: 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 65  ./* Maximum page
1cb0: 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 65   size.  The uppe
1cc0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 20  r bound on this 
1cd0: 76 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e 20  value is 65536. 
1ce0: 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a 2a   This a limit.**
1cf0: 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 20   imposed by the 
1d00: 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f 66  use of 16-bit of
1d10: 66 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 63  fsets within eac
1d20: 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 61  h page..**.** Ea
1d30: 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  rlier versions o
1d40: 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 64  f SQLite allowed
1d50: 20 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 61   the user to cha
1d60: 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 61  nge this value a
1d70: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t.** compile tim
1d80: 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c 6f  e. This is no lo
1d90: 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c 20  nger permitted, 
1da0: 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 74  on the grounds t
1db0: 68 61 74 20 69 74 20 63 72 65 61 74 65 73 0a 2a  hat it creates.*
1dc0: 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 74  * a library that
1dd0: 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 20   is technically 
1de0: 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 74  incompatible wit
1df0: 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 72  h an SQLite libr
1e00: 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  ary .** compiled
1e10: 20 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e   with a differen
1e20: 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 72  t limit. If a pr
1e30: 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 20  ocess operating 
1e40: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  on a database .*
1e50: 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 69  * with a page-si
1e60: 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 65  ze of 65536 byte
1e70: 73 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e 20  s crashes, then 
1e80: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 53  an instance of S
1e90: 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 6c  QLite .** compil
1ea0: 65 64 20 77 69 74 68 20 74 68 65 20 64 65 66 61  ed with the defa
1eb0: 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c 69  ult page-size li
1ec0: 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  mit will not be 
1ed0: 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b  able to rollback
1ee0: 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 64   .** the aborted
1ef0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
1f00: 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 6f  is could lead to
1f10: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
1f20: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  tion..*/.#ifdef 
1f30: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
1f40: 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 4c  SIZE.# undef SQL
1f50: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a  ITE_MAX_PAGE_SIZ
1f60: 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  E.#endif.#define
1f70: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45   SQLITE_MAX_PAGE
1f80: 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f 2a  _SIZE 65536.../*
1f90: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
1fa0: 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 61  size of a databa
1fb0: 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 6e  se page..*/.#ifn
1fc0: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55  def SQLITE_DEFAU
1fd0: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64  LT_PAGE_SIZE.# d
1fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
1ff0: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 31  AULT_PAGE_SIZE 1
2000: 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 53  024.#endif.#if S
2010: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41  QLITE_DEFAULT_PA
2020: 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f 4d  GE_SIZE>SQLITE_M
2030: 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 75  AX_PAGE_SIZE.# u
2040: 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41  ndef SQLITE_DEFA
2050: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20  ULT_PAGE_SIZE.# 
2060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
2070: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20  FAULT_PAGE_SIZE 
2080: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
2090: 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  SIZE.#endif../*.
20a0: 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 69  ** Ordinarily, i
20b0: 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 78  f no value is ex
20c0: 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 65  plicitly provide
20d0: 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 65  d, SQLite create
20e0: 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 77  s databases.** w
20f0: 69 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 51  ith page size SQ
2100: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47  LITE_DEFAULT_PAG
2110: 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 2c  E_SIZE. However,
2120: 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 69   based on certai
2130: 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 72  n.** device char
2140: 61 63 74 65 72 69 73 74 69 63 73 20 28 73 65 63  acteristics (sec
2150: 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 6f  tor-size and ato
2160: 6d 69 63 20 77 72 69 74 65 28 29 20 73 75 70 70  mic write() supp
2170: 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  ort),.** SQLite 
2180: 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 72  may choose a lar
2190: 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 20  ger value. This 
21a0: 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 20  constant is the 
21b0: 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a 2a  maximum value.**
21c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 6f   SQLite will cho
21d0: 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e 0a  ose on its own..
21e0: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
21f0: 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41  E_MAX_DEFAULT_PA
2200: 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65  GE_SIZE.# define
2210: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41   SQLITE_MAX_DEFA
2220: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 31  ULT_PAGE_SIZE 81
2230: 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51  92.#endif.#if SQ
2240: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54  LITE_MAX_DEFAULT
2250: 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54  _PAGE_SIZE>SQLIT
2260: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a  E_MAX_PAGE_SIZE.
2270: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  # undef SQLITE_M
2280: 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f  AX_DEFAULT_PAGE_
2290: 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51  SIZE.# define SQ
22a0: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54  LITE_MAX_DEFAULT
22b0: 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 54  _PAGE_SIZE SQLIT
22c0: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a  E_MAX_PAGE_SIZE.
22d0: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 4d  #endif.../*.** M
22e0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
22f0: 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 61   pages in one da
2300: 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
2310: 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c 6c  ** This is reall
2320: 79 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 75  y just the defau
2330: 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
2340: 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20   max_page_count 
2350: 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 20  pragma..** This 
2360: 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f 77  value can be low
2370: 65 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 29  ered (or raised)
2380: 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
2390: 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 6d  ng that the.** m
23a0: 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d 61  ax_page_count ma
23b0: 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  cro..*/.#ifndef 
23c0: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
23d0: 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 53  COUNT.# define S
23e0: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43  QLITE_MAX_PAGE_C
23f0: 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 0a  OUNT 1073741823.
2400: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61  #endif../*.** Ma
2410: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 6e  ximum length (in
2420: 20 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 70   bytes) of the p
2430: 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b 45  attern in a LIKE
2440: 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 72   or GLOB.** oper
2450: 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  ator..*/.#ifndef
2460: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45   SQLITE_MAX_LIKE
2470: 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 0a  _PATTERN_LENGTH.
2480: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2490: 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MAX_LIKE_PATTERN
24a0: 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 65  _LENGTH 50000.#e
24b0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 69  ndif../*.** Maxi
24c0: 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
24d0: 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
24e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 6c  ers..**.** A val
24f0: 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 68  ue of 1 means th
2500: 61 74 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  at a trigger pro
2510: 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 65  gram will not be
2520: 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 0a   able to itself.
2530: 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 67  ** fire any trig
2540: 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f 66  gers. A value of
2550: 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f   0 means that no
2560: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
2570: 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 79  s at all .** may
2580: 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a 2f   be executed..*/
2590: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
25a0: 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MAX_TRIGGER_DEPT
25b0: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  H.# define SQLIT
25c0: 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45  E_MAX_TRIGGER_DE
25d0: 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a  PTH 1000.#endif.
25e0: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
25f0: 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c 69   End of sqliteLi
2600: 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  mit.h **********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
2630: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
2640: 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72   Continuing wher
2650: 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e  e we left off in
2660: 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a   sqliteInt.h ***
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
2680: 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 69  ../* Disable nui
2690: 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 6f  sance warnings o
26a0: 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 6c  n Borland compil
26b0: 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e  ers */.#if defin
26c0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
26d0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 72  .#pragma warn -r
26e0: 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 6c  ch /* unreachabl
26f0: 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 6d  e code */.#pragm
2700: 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 43  a warn -ccc /* C
2710: 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 61  ondition is alwa
2720: 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65  ys true or false
2730: 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 6e   */.#pragma warn
2740: 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e 65   -aus /* Assigne
2750: 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 72  d value is never
2760: 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d 61   used */.#pragma
2770: 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 6f   warn -csu /* Co
2780: 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 61  mparing signed a
2790: 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a 23  nd unsigned */.#
27a0: 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 61  pragma warn -spa
27b0: 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 70   /* Suspicious p
27c0: 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 69  ointer arithmeti
27d0: 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20  c */.#endif../* 
27e0: 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f  Needed for vario
27f0: 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e  us definitions..
2800: 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 4e  . */.#ifndef _GN
2810: 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 6e  U_SOURCE.# defin
2820: 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65  e _GNU_SOURCE.#e
2830: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c  ndif../*.** Incl
2840: 75 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61  ude standard hea
2850: 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63  der files as nec
2860: 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66  essary.*/.#ifdef
2870: 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23   HAVE_STDINT_H.#
2880: 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e  include <stdint.
2890: 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66  h>.#endif.#ifdef
28a0: 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48   HAVE_INTTYPES_H
28b0: 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79  .#include <intty
28c0: 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f  pes.h>.#endif../
28d0: 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
28e0: 6e 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  ng macros are us
28f0: 65 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74  ed to cast point
2900: 65 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20  ers to integers 
2910: 61 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  and.** integers 
2920: 74 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68  to pointers.  Th
2930: 65 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69  e way you do thi
2940: 73 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  s varies from on
2950: 65 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f  e compiler.** to
2960: 20 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65   the next, so we
2970: 20 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20   have developed 
2980: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65  the following se
2990: 74 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65  t of #if stateme
29a0: 6e 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61  nts.** to genera
29b0: 74 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d  te appropriate m
29c0: 61 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65  acros for a wide
29d0: 20 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c   range of compil
29e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ers..**.** The c
29f0: 6f 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 61  orrect "ANSI" wa
2a00: 79 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20  y to do this is 
2a10: 74 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 74  to use the intpt
2a20: 72 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e  r_t type. .** Un
2a30: 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61  fortunately, tha
2a40: 74 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74  t typedef is not
2a50: 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c   available on al
2a60: 6c 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a  l compilers, or.
2a70: 2a 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 69  ** if it is avai
2a80: 6c 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72  lable, it requir
2a90: 65 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f  es an #include o
2aa0: 66 20 73 70 65 63 69 66 69 63 20 68 65 61 64 65  f specific heade
2ab0: 72 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20  rs.** that vary 
2ac0: 66 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65  from one machine
2ad0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a   to the next..**
2ae0: 0a 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30  .** Ticket #3860
2af0: 3a 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d  :  The llvm-gcc-
2b00: 34 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f  4.2 compiler fro
2b10: 6d 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f  m Apple chokes o
2b20: 6e 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a  n.** the ((void*
2b30: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29  )&((char*)0)[X])
2b40: 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74   construct.  But
2b50: 20 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20   MSVC chokes on 
2b60: 28 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a  ((void*)(X))..**
2b70: 20 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64   So we have to d
2b80: 65 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73  efine the macros
2b90: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61   in different wa
2ba0: 79 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ys depending on 
2bb0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e  the.** compiler.
2bc0: 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28  .*/.#if defined(
2bd0: 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f  __PTRDIFF_TYPE__
2be0: 29 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20  )  /* This case 
2bf0: 73 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20  should work for 
2c00: 47 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20  GCC */.# define 
2c10: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54  SQLITE_INT_TO_PT
2c20: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f  R(X)  ((void*)(_
2c30: 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29  _PTRDIFF_TYPE__)
2c40: 28 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51  (X)).# define SQ
2c50: 4c 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28  LITE_PTR_TO_INT(
2c60: 58 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52  X)  ((int)(__PTR
2c70: 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29  DIFF_TYPE__)(X))
2c80: 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28  .#elif !defined(
2c90: 5f 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20  __GNUC__)       
2ca0: 2f 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d  /* Works for com
2cb0: 70 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61  pilers other tha
2cc0: 6e 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69  n LLVM */.# defi
2cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f  ne SQLITE_INT_TO
2ce0: 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a  _PTR(X)  ((void*
2cf0: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29  )&((char*)0)[X])
2d00: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2d10: 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20  _PTR_TO_INT(X)  
2d20: 28 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58  ((int)(((char*)X
2d30: 29 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c  )-(char*)0)).#el
2d40: 69 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f  if defined(HAVE_
2d50: 53 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55  STDINT_H)   /* U
2d60: 73 65 20 74 68 69 73 20 63 61 73 65 20 69 66 20  se this case if 
2d70: 77 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 61  we have ANSI hea
2d80: 64 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65  ders */.# define
2d90: 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50   SQLITE_INT_TO_P
2da0: 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28  TR(X)  ((void*)(
2db0: 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20  intptr_t)(X)).# 
2dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54  define SQLITE_PT
2dd0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69  R_TO_INT(X)  ((i
2de0: 6e 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29  nt)(intptr_t)(X)
2df0: 29 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 20  ).#else         
2e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e10: 20 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20   /* Generates a 
2e20: 77 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74  warning - but it
2e30: 20 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f   always works */
2e40: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2e50: 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20  _INT_TO_PTR(X)  
2e60: 28 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64  ((void*)(X)).# d
2e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52  efine SQLITE_PTR
2e80: 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e  _TO_INT(X)  ((in
2e90: 74 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f  t)(X)).#endif../
2ea0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
2eb0: 54 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f  THREADSAFE macro
2ec0: 20 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 64   must be defined
2ed0: 20 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a   as 0, 1, or 2..
2ee0: 2a 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78  ** 0 means mutex
2ef0: 65 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74  es are permanent
2f00: 6c 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74  ly disable and t
2f10: 68 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65  he library is ne
2f20: 76 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66  ver.** threadsaf
2f30: 65 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20  e.  1 means the 
2f40: 6c 69 62 72 61 72 79 20 69 73 20 73 65 72 69 61  library is seria
2f50: 6c 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 74  lized which is t
2f60: 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65  he highest.** le
2f70: 76 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66  vel of threadsaf
2f80: 65 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68  ety.  2 means th
2f90: 65 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c 74  e libary is mult
2fa0: 69 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74  ithreaded - mult
2fb0: 69 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20  iple.** threads 
2fc0: 63 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61  can use SQLite a
2fd0: 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
2fe0: 20 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20   threads try to 
2ff0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
3000: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3010: 69 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  ion at the same 
3020: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65  time..**.** Olde
3030: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
3040: 4c 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74  Lite used an opt
3050: 69 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45  ional THREADSAFE
3060: 20 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75   macro..** We su
3070: 70 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c  pport that for l
3080: 65 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64  egacy..*/.#if !d
3090: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48  efined(SQLITE_TH
30a0: 52 45 41 44 53 41 46 45 29 0a 23 69 66 20 64 65  READSAFE).#if de
30b0: 66 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45  fined(THREADSAFE
30c0: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  ).# define SQLIT
30d0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 54 48 52  E_THREADSAFE THR
30e0: 45 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23 20  EADSAFE.#else.# 
30f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 48  define SQLITE_TH
3100: 52 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49 4d  READSAFE 1 /* IM
3110: 50 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30 39  P: R-07272-22309
3120: 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69   */.#endif.#endi
3130: 66 0a 0a 2f 2a 0a 2a 2a 20 50 6f 77 65 72 73 61  f../*.** Powersa
3140: 66 65 20 6f 76 65 72 77 72 69 74 65 20 69 73 20  fe overwrite is 
3150: 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
3160: 42 75 74 20 63 61 6e 20 62 65 20 74 75 72 6e 65  But can be turne
3170: 64 20 6f 66 66 20 75 73 69 6e 67 0a 2a 2a 20 74  d off using.** t
3180: 68 65 20 2d 44 53 51 4c 49 54 45 5f 50 4f 57 45  he -DSQLITE_POWE
3190: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 3d  RSAFE_OVERWRITE=
31a0: 30 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 6f  0 command-line o
31b0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ption..*/.#ifnde
31c0: 66 20 53 51 4c 49 54 45 5f 50 4f 57 45 52 53 41  f SQLITE_POWERSA
31d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 0a 23 20 64  FE_OVERWRITE.# d
31e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 4f 57  efine SQLITE_POW
31f0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
3200: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a   1.#endif../*.**
3210: 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46 41   The SQLITE_DEFA
3220: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 20 6d 61  ULT_MEMSTATUS ma
3230: 63 72 6f 20 6d 75 73 74 20 62 65 20 64 65 66 69  cro must be defi
3240: 6e 65 64 20 61 73 20 65 69 74 68 65 72 20 30 20  ned as either 0 
3250: 6f 72 20 31 2e 0a 2a 2a 20 49 74 20 64 65 74 65  or 1..** It dete
3260: 72 6d 69 6e 65 73 20 77 68 65 74 68 65 72 20 6f  rmines whether o
3270: 72 20 6e 6f 74 20 74 68 65 20 66 65 61 74 75 72  r not the featur
3280: 65 73 20 72 65 6c 61 74 65 64 20 74 6f 20 0a 2a  es related to .*
3290: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
32a0: 4d 45 4d 53 54 41 54 55 53 20 61 72 65 20 61 76  MEMSTATUS are av
32b0: 61 69 6c 61 62 6c 65 20 62 79 20 64 65 66 61 75  ailable by defau
32c0: 6c 74 20 6f 72 20 6e 6f 74 2e 20 54 68 69 73 20  lt or not. This 
32d0: 76 61 6c 75 65 20 63 61 6e 0a 2a 2a 20 62 65 20  value can.** be 
32e0: 6f 76 65 72 72 69 64 64 65 6e 20 61 74 20 72 75  overridden at ru
32f0: 6e 74 69 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ntime using the 
3300: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
3310: 20 41 50 49 2e 0a 2a 2f 0a 23 69 66 20 21 64 65   API..*/.#if !de
3320: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 46  fined(SQLITE_DEF
3330: 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 29 0a  AULT_MEMSTATUS).
3340: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
3350: 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
3360: 53 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  S 1.#endif../*.*
3370: 2a 20 45 78 61 63 74 6c 79 20 6f 6e 65 20 6f 66  * Exactly one of
3380: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d   the following m
3390: 61 63 72 6f 73 20 6d 75 73 74 20 62 65 20 64 65  acros must be de
33a0: 66 69 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  fined in order t
33b0: 6f 0a 2a 2a 20 73 70 65 63 69 66 79 20 77 68 69  o.** specify whi
33c0: 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ch memory alloca
33d0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 74  tion subsystem t
33e0: 6f 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 20 20 20  o use..**.**    
33f0: 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d   SQLITE_SYSTEM_M
3400: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 20 2f  ALLOC          /
3410: 2f 20 55 73 65 20 6e 6f 72 6d 61 6c 20 73 79 73  / Use normal sys
3420: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 20  tem malloc().** 
3430: 20 20 20 20 53 51 4c 49 54 45 5f 57 49 4e 33 32      SQLITE_WIN32
3440: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20  _MALLOC         
3450: 20 20 2f 2f 20 55 73 65 20 57 69 6e 33 32 20 6e    // Use Win32 n
3460: 61 74 69 76 65 20 68 65 61 70 20 41 50 49 0a 2a  ative heap API.*
3470: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 5a 45 52  *     SQLITE_ZER
3480: 4f 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  O_MALLOC        
3490: 20 20 20 20 2f 2f 20 55 73 65 20 61 20 73 74 75      // Use a stu
34a0: 62 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  b allocator that
34b0: 20 61 6c 77 61 79 73 20 66 61 69 6c 73 0a 2a 2a   always fails.**
34c0: 20 20 20 20 20 53 51 4c 49 54 45 5f 4d 45 4d 44       SQLITE_MEMD
34d0: 45 42 55 47 20 20 20 20 20 20 20 20 20 20 20 20  EBUG            
34e0: 20 20 20 2f 2f 20 44 65 62 75 67 67 69 6e 67 20     // Debugging 
34f0: 76 65 72 73 69 6f 6e 20 6f 66 20 73 79 73 74 65  version of syste
3500: 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a 2a 2a  m malloc().**.**
3510: 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69 66 20   On Windows, if 
3520: 74 68 65 20 53 51 4c 49 54 45 5f 57 49 4e 33 32  the SQLITE_WIN32
3530: 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41 54 45  _MALLOC_VALIDATE
3540: 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e 65   macro is define
3550: 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61 73 73  d and the.** ass
3560: 65 72 74 28 29 20 6d 61 63 72 6f 20 69 73 20 65  ert() macro is e
3570: 6e 61 62 6c 65 64 2c 20 65 61 63 68 20 63 61 6c  nabled, each cal
3580: 6c 20 69 6e 74 6f 20 74 68 65 20 57 69 6e 33 32  l into the Win32
3590: 20 6e 61 74 69 76 65 20 68 65 61 70 20 73 75 62   native heap sub
35a0: 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c 20 63  system.** will c
35b0: 61 75 73 65 20 48 65 61 70 56 61 6c 69 64 61 74  ause HeapValidat
35c0: 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e 20  e to be called. 
35d0: 20 49 66 20 68 65 61 70 20 76 61 6c 69 64 61 74   If heap validat
35e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69 6c 2c  ion should fail,
35f0: 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e   an.** assertion
3600: 20 77 69 6c 6c 20 62 65 20 74 72 69 67 67 65 72   will be trigger
3610: 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74 6f  ed..**.** (Histo
3620: 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54 68 65  rical note:  The
3630: 72 65 20 75 73 65 64 20 74 6f 20 62 65 20 73 65  re used to be se
3640: 76 65 72 61 6c 20 6f 74 68 65 72 20 6f 70 74 69  veral other opti
3650: 6f 6e 73 2c 20 62 75 74 20 77 65 27 76 65 0a 2a  ons, but we've.*
3660: 2a 20 70 61 72 65 64 20 69 74 20 64 6f 77 6e 20  * pared it down 
3670: 74 6f 20 6a 75 73 74 20 74 68 65 73 65 20 74 68  to just these th
3680: 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66 20 6e  ree.).**.** If n
3690: 6f 6e 65 20 6f 66 20 74 68 65 20 61 62 6f 76 65  one of the above
36a0: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
36b0: 65 6e 20 73 65 74 20 53 51 4c 49 54 45 5f 53 59  en set SQLITE_SY
36c0: 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73 0a 2a  STEM_MALLOC as.*
36d0: 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 0a 2a  * the default..*
36e0: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 51  /.#if defined(SQ
36f0: 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c  LITE_SYSTEM_MALL
3700: 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66 69 6e 65  OC) \.  + define
3710: 64 28 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d  d(SQLITE_WIN32_M
3720: 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66  ALLOC) \.  + def
3730: 69 6e 65 64 28 53 51 4c 49 54 45 5f 5a 45 52 4f  ined(SQLITE_ZERO
3740: 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64  _MALLOC) \.  + d
3750: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45  efined(SQLITE_ME
3760: 4d 44 45 42 55 47 29 3e 31 0a 23 20 65 72 72 6f  MDEBUG)>1.# erro
3770: 72 20 22 54 77 6f 20 6f 72 20 6d 6f 72 65 20 6f  r "Two or more o
3780: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
3790: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e  compile-time con
37a0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
37b0: 6e 73 5c 0a 20 61 72 65 20 64 65 66 69 6e 65 64  ns\. are defined
37c0: 20 62 75 74 20 61 74 20 6d 6f 73 74 20 6f 6e 65   but at most one
37d0: 20 69 73 20 61 6c 6c 6f 77 65 64 3a 5c 0a 20 53   is allowed:\. S
37e0: 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c  QLITE_SYSTEM_MAL
37f0: 4c 4f 43 2c 20 53 51 4c 49 54 45 5f 57 49 4e 33  LOC, SQLITE_WIN3
3800: 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 45  2_MALLOC, SQLITE
3810: 5f 4d 45 4d 44 45 42 55 47 2c 5c 0a 20 53 51 4c  _MEMDEBUG,\. SQL
3820: 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 22  ITE_ZERO_MALLOC"
3830: 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69  .#endif.#if defi
3840: 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45  ned(SQLITE_SYSTE
3850: 4d 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20  M_MALLOC) \.  + 
3860: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 57  defined(SQLITE_W
3870: 49 4e 33 32 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20  IN32_MALLOC) \. 
3880: 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54   + defined(SQLIT
3890: 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 29 20 5c  E_ZERO_MALLOC) \
38a0: 0a 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c  .  + defined(SQL
38b0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d 3d 30  ITE_MEMDEBUG)==0
38c0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
38d0: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 31  _SYSTEM_MALLOC 1
38e0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49  .#endif../*.** I
38f0: 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f  f SQLITE_MALLOC_
3900: 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20 6e 6f  SOFT_LIMIT is no
3910: 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 79  t zero, then try
3920: 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a 2a 20   to keep the.** 
3930: 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  sizes of memory 
3940: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65 6c 6f  allocations belo
3950: 77 20 74 68 69 73 20 76 61 6c 75 65 20 77 68 65  w this value whe
3960: 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2f 0a  re possible..*/.
3970: 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c  #if !defined(SQL
3980: 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f  ITE_MALLOC_SOFT_
3990: 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e 65 20  LIMIT).# define 
39a0: 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f  SQLITE_MALLOC_SO
39b0: 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a 23 65  FT_LIMIT 1024.#e
39c0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65 20 6e  ndif../*.** We n
39d0: 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20 5f 58  eed to define _X
39e0: 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73 20 66  OPEN_SOURCE as f
39f0: 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65 72 20  ollows in order 
3a00: 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72 65 63  to enable.** rec
3a10: 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 20 6f  ursive mutexes o
3a20: 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79 73 74  n most Unix syst
3a30: 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20 4f 53  ems.  But Mac OS
3a40: 20 58 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e   X is different.
3a50: 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e 5f 53  .** The _XOPEN_S
3a60: 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63 61 75  OURCE define cau
3a70: 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f 72  ses problems for
3a80: 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61 72 65   Mac OS X we are
3a90: 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69 74 20   told,.** so it 
3aa0: 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 72 65  is omitted there
3ab0: 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
3ac0: 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74 65 72  673..**.** Later
3ad0: 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74 20 5f   we learn that _
3ae0: 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69 73 20  XOPEN_SOURCE is 
3af0: 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f 72 72  poorly or incorr
3b00: 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ectly.** impleme
3b10: 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73 79 73  nted on some sys
3b20: 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61 76 6f  tems.  So we avo
3b30: 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74 20 61  id defining it a
3b40: 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74 20 69  t all.** if it i
3b50: 73 20 61 6c 72 65 61 64 79 20 64 65 66 69 6e 65  s already define
3b60: 64 20 6f 72 20 69 66 20 69 74 20 69 73 20 75 6e  d or if it is un
3b70: 6e 65 65 64 65 64 20 62 65 63 61 75 73 65 20 77  needed because w
3b80: 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64 6f 69  e are.** not doi
3b90: 6e 67 20 61 20 74 68 72 65 61 64 73 61 66 65 20  ng a threadsafe 
3ba0: 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74 20 23  build.  Ticket #
3bb0: 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2681..**.** See 
3bc0: 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32 37 34  also ticket #274
3bd0: 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e  1..*/.#if !defin
3be0: 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45  ed(_XOPEN_SOURCE
3bf0: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 5f  ) && !defined(__
3c00: 44 41 52 57 49 4e 5f 5f 29 20 5c 0a 20 26 26 20  DARWIN__) \. && 
3c10: 21 64 65 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45  !defined(__APPLE
3c20: 5f 5f 29 20 26 26 20 53 51 4c 49 54 45 5f 54 48  __) && SQLITE_TH
3c30: 52 45 41 44 53 41 46 45 0a 23 20 20 64 65 66 69  READSAFE.#  defi
3c40: 6e 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45  ne _XOPEN_SOURCE
3c50: 20 35 30 30 20 20 2f 2a 20 4e 65 65 64 65 64 20   500  /* Needed 
3c60: 74 6f 20 65 6e 61 62 6c 65 20 70 74 68 72 65 61  to enable pthrea
3c70: 64 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  d recursive mute
3c80: 78 65 73 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f  xes */.#endif../
3c90: 2a 0a 2a 2a 20 54 68 65 20 54 43 4c 20 68 65 61  *.** The TCL hea
3ca0: 64 65 72 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65  ders are only ne
3cb0: 65 64 65 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c  eded when compil
3cc0: 69 6e 67 20 74 68 65 20 54 43 4c 20 62 69 6e 64  ing the TCL bind
3cd0: 69 6e 67 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66  ings..*/.#if def
3ce0: 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 43 4c 29  ined(SQLITE_TCL)
3cf0: 20 7c 7c 20 64 65 66 69 6e 65 64 28 54 43 4c 53   || defined(TCLS
3d00: 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 3c 74 63  H).# include <tc
3d10: 6c 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  l.h>.#endif../*.
3d20: 2a 2a 20 4e 44 45 42 55 47 20 61 6e 64 20 53 51  ** NDEBUG and SQ
3d30: 4c 49 54 45 5f 44 45 42 55 47 20 61 72 65 20 6f  LITE_DEBUG are o
3d40: 70 70 6f 73 69 74 65 73 2e 20 20 49 74 20 73 68  pposites.  It sh
3d50: 6f 75 6c 64 20 61 6c 77 61 79 73 20 62 65 20 74  ould always be t
3d60: 72 75 65 20 74 68 61 74 0a 2a 2a 20 64 65 66 69  rue that.** defi
3d70: 6e 65 64 28 4e 44 45 42 55 47 29 3d 3d 21 64 65  ned(NDEBUG)==!de
3d80: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 42  fined(SQLITE_DEB
3d90: 55 47 29 2e 20 20 49 66 20 74 68 69 73 20 69 73  UG).  If this is
3da0: 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 74   not currently t
3db0: 72 75 65 2c 0a 2a 2a 20 6d 61 6b 65 20 69 74 20  rue,.** make it 
3dc0: 74 72 75 65 20 62 79 20 64 65 66 69 6e 69 6e 67  true by defining
3dd0: 20 6f 72 20 75 6e 64 65 66 69 6e 69 6e 67 20 4e   or undefining N
3de0: 44 45 42 55 47 2e 0a 2a 2a 0a 2a 2a 20 53 65 74  DEBUG..**.** Set
3df0: 74 69 6e 67 20 4e 44 45 42 55 47 20 6d 61 6b 65  ting NDEBUG make
3e00: 73 20 74 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c  s the code small
3e10: 65 72 20 61 6e 64 20 72 75 6e 20 66 61 73 74 65  er and run faste
3e20: 72 20 62 79 20 64 69 73 61 62 6c 69 6e 67 20 74  r by disabling t
3e30: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 61 73 73  he.** number ass
3e40: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
3e50: 20 69 6e 20 74 68 65 20 63 6f 64 65 2e 20 20 53   in the code.  S
3e60: 6f 20 77 65 20 77 61 6e 74 20 74 68 65 20 64 65  o we want the de
3e70: 66 61 75 6c 74 20 61 63 74 69 6f 6e 0a 2a 2a 20  fault action.** 
3e80: 74 6f 20 62 65 20 66 6f 72 20 4e 44 45 42 55 47  to be for NDEBUG
3e90: 20 74 6f 20 62 65 20 73 65 74 20 61 6e 64 20 4e   to be set and N
3ea0: 44 45 42 55 47 20 74 6f 20 62 65 20 75 6e 64 65  DEBUG to be unde
3eb0: 66 69 6e 65 64 20 6f 6e 6c 79 20 69 66 20 53 51  fined only if SQ
3ec0: 4c 49 54 45 5f 44 45 42 55 47 0a 2a 2a 20 69 73  LITE_DEBUG.** is
3ed0: 20 73 65 74 2e 20 20 54 68 75 73 20 4e 44 45 42   set.  Thus NDEB
3ee0: 55 47 20 62 65 63 6f 6d 65 73 20 61 6e 20 6f 70  UG becomes an op
3ef0: 74 2d 69 6e 20 72 61 74 68 65 72 20 74 68 61 6e  t-in rather than
3f00: 20 61 6e 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66   an opt-out.** f
3f10: 65 61 74 75 72 65 2e 0a 2a 2f 0a 23 69 66 20 21  eature..*/.#if !
3f20: 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29 20  defined(NDEBUG) 
3f30: 26 26 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49  && !defined(SQLI
3f40: 54 45 5f 44 45 42 55 47 29 20 0a 23 20 64 65 66  TE_DEBUG) .# def
3f50: 69 6e 65 20 4e 44 45 42 55 47 20 31 0a 23 65 6e  ine NDEBUG 1.#en
3f60: 64 69 66 0a 23 69 66 20 64 65 66 69 6e 65 64 28  dif.#if defined(
3f70: 4e 44 45 42 55 47 29 20 26 26 20 64 65 66 69 6e  NDEBUG) && defin
3f80: 65 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29  ed(SQLITE_DEBUG)
3f90: 0a 23 20 75 6e 64 65 66 20 4e 44 45 42 55 47 0a  .# undef NDEBUG.
3fa0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
3fb0: 65 20 74 65 73 74 63 61 73 65 28 29 20 6d 61 63  e testcase() mac
3fc0: 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20 61 69  ro is used to ai
3fd0: 64 20 69 6e 20 63 6f 76 65 72 61 67 65 20 74 65  d in coverage te
3fe0: 73 74 69 6e 67 2e 20 20 57 68 65 6e 20 0a 2a 2a  sting.  When .**
3ff0: 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 20   doing coverage 
4000: 74 65 73 74 69 6e 67 2c 20 74 68 65 20 63 6f 6e  testing, the con
4010: 64 69 74 69 6f 6e 20 69 6e 73 69 64 65 20 74 68  dition inside th
4020: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
4030: 20 74 65 73 74 63 61 73 65 28 29 20 6d 75 73 74   testcase() must
4040: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 62 6f   be evaluated bo
4050: 74 68 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73  th true and fals
4060: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  e in order to.**
4070: 20 67 65 74 20 66 75 6c 6c 20 62 72 61 6e 63 68   get full branch
4080: 20 63 6f 76 65 72 61 67 65 2e 20 20 54 68 65 20   coverage.  The 
4090: 74 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 6f  testcase() macro
40a0: 20 69 73 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20   is inserted.** 
40b0: 74 6f 20 68 65 6c 70 20 65 6e 73 75 72 65 20 61  to help ensure a
40c0: 64 65 71 75 61 74 65 20 74 65 73 74 20 63 6f 76  dequate test cov
40d0: 65 72 61 67 65 20 69 6e 20 70 6c 61 63 65 73 20  erage in places 
40e0: 77 68 65 72 65 20 73 69 6d 70 6c 65 0a 2a 2a 20  where simple.** 
40f0: 63 6f 6e 64 69 74 69 6f 6e 2f 64 65 63 69 73 69  condition/decisi
4100: 6f 6e 20 63 6f 76 65 72 61 67 65 20 69 73 20 69  on coverage is i
4110: 6e 61 64 65 71 75 61 74 65 2e 20 20 46 6f 72 20  nadequate.  For 
4120: 65 78 61 6d 70 6c 65 2c 20 74 65 73 74 63 61 73  example, testcas
4130: 65 28 29 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  e().** can be us
4140: 65 64 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  ed to make sure 
4150: 62 6f 75 6e 64 61 72 79 20 76 61 6c 75 65 73 20  boundary values 
4160: 61 72 65 20 74 65 73 74 65 64 2e 20 20 46 6f 72  are tested.  For
4170: 0a 2a 2a 20 62 69 74 6d 61 73 6b 20 74 65 73 74  .** bitmask test
4180: 73 2c 20 74 65 73 74 63 61 73 65 28 29 20 63 61  s, testcase() ca
4190: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6d 61 6b  n be used to mak
41a0: 65 20 73 75 72 65 20 65 61 63 68 20 62 69 74 0a  e sure each bit.
41b0: 2a 2a 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e  ** is significan
41c0: 74 20 61 6e 64 20 75 73 65 64 20 61 74 20 6c 65  t and used at le
41d0: 61 73 74 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 77  ast once.  On sw
41e0: 69 74 63 68 20 73 74 61 74 65 6d 65 6e 74 73 0a  itch statements.
41f0: 2a 2a 20 77 68 65 72 65 20 6d 75 6c 74 69 70 6c  ** where multipl
4200: 65 20 63 61 73 65 73 20 67 6f 20 74 6f 20 74 68  e cases go to th
4210: 65 20 73 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20  e same block of 
4220: 63 6f 64 65 2c 20 74 65 73 74 63 61 73 65 28 29  code, testcase()
4230: 0a 2a 2a 20 63 61 6e 20 69 6e 73 75 72 65 20 74  .** can insure t
4240: 68 61 74 20 61 6c 6c 20 63 61 73 65 73 20 61 72  hat all cases ar
4250: 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a  e evaluated..**.
4260: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
4270: 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 0a 53  _COVERAGE_TEST.S
4280: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 20 20  QLITE_PRIVATE   
4290: 76 6f 69 64 20 73 71 6c 69 74 65 33 43 6f 76 65  void sqlite3Cove
42a0: 72 61 67 65 28 69 6e 74 29 3b 0a 23 20 64 65 66  rage(int);.# def
42b0: 69 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 20  ine testcase(X) 
42c0: 20 69 66 28 20 58 20 29 7b 20 73 71 6c 69 74 65   if( X ){ sqlite
42d0: 33 43 6f 76 65 72 61 67 65 28 5f 5f 4c 49 4e 45  3Coverage(__LINE
42e0: 5f 5f 29 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 64  __); }.#else.# d
42f0: 65 66 69 6e 65 20 74 65 73 74 63 61 73 65 28 58  efine testcase(X
4300: 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ).#endif../*.** 
4310: 54 68 65 20 54 45 53 54 4f 4e 4c 59 20 6d 61 63  The TESTONLY mac
4320: 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  ro is used to en
4330: 63 6c 6f 73 65 20 76 61 72 69 61 62 6c 65 20 64  close variable d
4340: 65 63 6c 61 72 61 74 69 6f 6e 73 20 6f 72 0a 2a  eclarations or.*
4350: 2a 20 6f 74 68 65 72 20 62 69 74 73 20 6f 66 20  * other bits of 
4360: 63 6f 64 65 20 74 68 61 74 20 61 72 65 20 6e 65  code that are ne
4370: 65 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  eded to support 
4380: 74 68 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  the arguments.**
4390: 20 77 69 74 68 69 6e 20 74 65 73 74 63 61 73 65   within testcase
43a0: 28 29 20 61 6e 64 20 61 73 73 65 72 74 28 29 20  () and assert() 
43b0: 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 21  macros..*/.#if !
43c0: 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29 20  defined(NDEBUG) 
43d0: 7c 7c 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54  || defined(SQLIT
43e0: 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 29  E_COVERAGE_TEST)
43f0: 0a 23 20 64 65 66 69 6e 65 20 54 45 53 54 4f 4e  .# define TESTON
4400: 4c 59 28 58 29 20 20 58 0a 23 65 6c 73 65 0a 23  LY(X)  X.#else.#
4410: 20 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59   define TESTONLY
4420: 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  (X).#endif../*.*
4430: 2a 20 53 6f 6d 65 74 69 6d 65 73 20 77 65 20 6e  * Sometimes we n
4440: 65 65 64 20 61 20 73 6d 61 6c 6c 20 61 6d 6f 75  eed a small amou
4450: 6e 74 20 6f 66 20 63 6f 64 65 20 73 75 63 68 20  nt of code such 
4460: 61 73 20 61 20 76 61 72 69 61 62 6c 65 20 69 6e  as a variable in
4470: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a 20  itialization.** 
4480: 74 6f 20 73 65 74 75 70 20 66 6f 72 20 61 20 6c  to setup for a l
4490: 61 74 65 72 20 61 73 73 65 72 74 28 29 20 73 74  ater assert() st
44a0: 61 74 65 6d 65 6e 74 2e 20 20 57 65 20 64 6f 20  atement.  We do 
44b0: 6e 6f 74 20 77 61 6e 74 20 74 68 69 73 20 63 6f  not want this co
44c0: 64 65 20 74 6f 0a 2a 2a 20 61 70 70 65 61 72 20  de to.** appear 
44d0: 77 68 65 6e 20 61 73 73 65 72 74 28 29 20 69 73  when assert() is
44e0: 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20   disabled.  The 
44f0: 66 6f 6c 6c 6f 77 69 6e 67 20 6d 61 63 72 6f 20  following macro 
4500: 69 73 20 74 68 65 72 65 66 6f 72 65 0a 2a 2a 20  is therefore.** 
4510: 75 73 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  used to contain 
4520: 74 68 61 74 20 73 65 74 75 70 20 63 6f 64 65 2e  that setup code.
4530: 20 20 54 68 65 20 22 56 56 41 22 20 61 63 72 6f    The "VVA" acro
4540: 6e 79 6d 20 73 74 61 6e 64 73 20 66 6f 72 0a 2a  nym stands for.*
4550: 2a 20 22 56 65 72 69 66 69 63 61 74 69 6f 6e 2c  * "Verification,
4560: 20 56 61 6c 69 64 61 74 69 6f 6e 2c 20 61 6e 64   Validation, and
4570: 20 41 63 63 72 65 64 69 74 61 74 69 6f 6e 22 2e   Accreditation".
4580: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
4590: 2c 20 74 68 65 0a 2a 2a 20 63 6f 64 65 20 77 69  , the.** code wi
45a0: 74 68 69 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 20  thin VVA_ONLY() 
45b0: 77 69 6c 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 75  will only run du
45c0: 72 69 6e 67 20 76 65 72 69 66 69 63 61 74 69 6f  ring verificatio
45d0: 6e 20 70 72 6f 63 65 73 73 65 73 2e 0a 2a 2f 0a  n processes..*/.
45e0: 23 69 66 6e 64 65 66 20 4e 44 45 42 55 47 0a 23  #ifndef NDEBUG.#
45f0: 20 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59   define VVA_ONLY
4600: 28 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 64  (X)  X.#else.# d
4610: 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58  efine VVA_ONLY(X
4620: 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ).#endif../*.** 
4630: 54 68 65 20 41 4c 57 41 59 53 20 61 6e 64 20 4e  The ALWAYS and N
4640: 45 56 45 52 20 6d 61 63 72 6f 73 20 73 75 72 72  EVER macros surr
4650: 6f 75 6e 64 20 62 6f 6f 6c 65 61 6e 20 65 78 70  ound boolean exp
4660: 72 65 73 73 69 6f 6e 73 20 77 68 69 63 68 20 0a  ressions which .
4670: 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ** are intended 
4680: 74 6f 20 61 6c 77 61 79 73 20 62 65 20 74 72 75  to always be tru
4690: 65 20 6f 72 20 66 61 6c 73 65 2c 20 72 65 73 70  e or false, resp
46a0: 65 63 74 69 76 65 6c 79 2e 20 20 53 75 63 68 0a  ectively.  Such.
46b0: 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63  ** expressions c
46c0: 6f 75 6c 64 20 62 65 20 6f 6d 69 74 74 65 64 20  ould be omitted 
46d0: 66 72 6f 6d 20 74 68 65 20 63 6f 64 65 20 63 6f  from the code co
46e0: 6d 70 6c 65 74 65 6c 79 2e 20 20 42 75 74 20 74  mpletely.  But t
46f0: 68 65 79 0a 2a 2a 20 61 72 65 20 69 6e 63 6c 75  hey.** are inclu
4700: 64 65 64 20 69 6e 20 61 20 66 65 77 20 63 61 73  ded in a few cas
4710: 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  es in order to e
4720: 6e 68 61 6e 63 65 20 74 68 65 20 72 65 73 69 6c  nhance the resil
4730: 69 65 6e 63 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  ience.** of SQLi
4740: 74 65 20 74 6f 20 75 6e 65 78 70 65 63 74 65 64  te to unexpected
4750: 20 62 65 68 61 76 69 6f 72 20 2d 20 74 6f 20 6d   behavior - to m
4760: 61 6b 65 20 74 68 65 20 63 6f 64 65 20 22 73 65  ake the code "se
4770: 6c 66 2d 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 6f  lf-healing".** o
4780: 72 20 22 64 75 63 74 69 6c 65 22 20 72 61 74 68  r "ductile" rath
4790: 65 72 20 74 68 61 6e 20 62 65 69 6e 67 20 22 62  er than being "b
47a0: 72 69 74 74 6c 65 22 20 61 6e 64 20 63 72 61 73  rittle" and cras
47b0: 68 69 6e 67 20 61 74 20 74 68 65 20 66 69 72 73  hing at the firs
47c0: 74 0a 2a 2a 20 68 69 6e 74 20 6f 66 20 75 6e 70  t.** hint of unp
47d0: 6c 61 6e 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  lanned behavior.
47e0: 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
47f0: 77 6f 72 64 73 2c 20 41 4c 57 41 59 53 20 61 6e  words, ALWAYS an
4800: 64 20 4e 45 56 45 52 20 61 72 65 20 61 64 64 65  d NEVER are adde
4810: 64 20 66 6f 72 20 64 65 66 65 6e 73 69 76 65 20  d for defensive 
4820: 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  code..**.** When
4830: 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 20   doing coverage 
4840: 74 65 73 74 69 6e 67 20 41 4c 57 41 59 53 20 61  testing ALWAYS a
4850: 6e 64 20 4e 45 56 45 52 20 61 72 65 20 68 61 72  nd NEVER are har
4860: 64 2d 63 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 65  d-coded to.** be
4870: 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 20   true and false 
4880: 73 6f 20 74 68 61 74 20 74 68 65 20 75 6e 72 65  so that the unre
4890: 61 63 68 61 62 6c 65 20 63 6f 64 65 20 74 68 65  achable code the
48a0: 6e 20 73 70 65 63 69 66 79 20 77 69 6c 6c 0a 2a  n specify will.*
48b0: 2a 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64  * not be counted
48c0: 20 61 73 20 75 6e 74 65 73 74 65 64 20 63 6f 64   as untested cod
48d0: 65 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  e..*/.#if define
48e0: 64 28 53 51 4c 49 54 45 5f 43 4f 56 45 52 41 47  d(SQLITE_COVERAG
48f0: 45 5f 54 45 53 54 29 0a 23 20 64 65 66 69 6e 65  E_TEST).# define
4900: 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20   ALWAYS(X)      
4910: 28 31 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56  (1).# define NEV
4920: 45 52 28 58 29 20 20 20 20 20 20 20 28 30 29 0a  ER(X)       (0).
4930: 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 4e  #elif !defined(N
4940: 44 45 42 55 47 29 0a 23 20 64 65 66 69 6e 65 20  DEBUG).# define 
4950: 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28  ALWAYS(X)      (
4960: 28 58 29 3f 31 3a 28 61 73 73 65 72 74 28 30 29  (X)?1:(assert(0)
4970: 2c 30 29 29 0a 23 20 64 65 66 69 6e 65 20 4e 45  ,0)).# define NE
4980: 56 45 52 28 58 29 20 20 20 20 20 20 20 28 28 58  VER(X)       ((X
4990: 29 3f 28 61 73 73 65 72 74 28 30 29 2c 31 29 3a  )?(assert(0),1):
49a0: 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  0).#else.# defin
49b0: 65 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20  e ALWAYS(X)     
49c0: 20 28 58 29 0a 23 20 64 65 66 69 6e 65 20 4e 45   (X).# define NE
49d0: 56 45 52 28 58 29 20 20 20 20 20 20 20 28 58 29  VER(X)       (X)
49e0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 52  .#endif../*.** R
49f0: 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d  eturn true (non-
4a00: 7a 65 72 6f 29 20 69 66 20 74 68 65 20 69 6e 70  zero) if the inp
4a10: 75 74 20 69 73 20 61 20 69 6e 74 65 67 65 72 20  ut is a integer 
4a20: 74 68 61 74 20 69 73 20 74 6f 6f 20 6c 61 72 67  that is too larg
4a30: 65 0a 2a 2a 20 74 6f 20 66 69 74 20 69 6e 20 33  e.** to fit in 3
4a40: 32 2d 62 69 74 73 2e 20 20 54 68 69 73 20 6d 61  2-bits.  This ma
4a50: 63 72 6f 20 69 73 20 75 73 65 64 20 69 6e 73 69  cro is used insi
4a60: 64 65 20 6f 66 20 76 61 72 69 6f 75 73 20 74 65  de of various te
4a70: 73 74 63 61 73 65 28 29 0a 2a 2a 20 6d 61 63 72  stcase().** macr
4a80: 6f 73 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  os to verify tha
4a90: 74 20 77 65 20 68 61 76 65 20 74 65 73 74 65 64  t we have tested
4aa0: 20 53 51 4c 69 74 65 20 66 6f 72 20 6c 61 72 67   SQLite for larg
4ab0: 65 2d 66 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a  e-file support..
4ac0: 2a 2f 0a 23 64 65 66 69 6e 65 20 49 53 5f 42 49  */.#define IS_BI
4ad0: 47 5f 49 4e 54 28 58 29 20 20 28 28 28 58 29 26  G_INT(X)  (((X)&
4ae0: 7e 28 69 36 34 29 30 78 66 66 66 66 66 66 66 66  ~(i64)0xffffffff
4af0: 29 21 3d 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  )!=0)../*.** The
4b00: 20 6d 61 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 28   macro unlikely(
4b10: 29 20 69 73 20 61 20 68 69 6e 74 20 74 68 61 74  ) is a hint that
4b20: 20 73 75 72 72 6f 75 6e 64 73 20 61 20 62 6f 6f   surrounds a boo
4b30: 6c 65 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  lean.** expressi
4b40: 6f 6e 20 74 68 61 74 20 69 73 20 75 73 75 61 6c  on that is usual
4b50: 6c 79 20 66 61 6c 73 65 2e 20 20 4d 61 63 72 6f  ly false.  Macro
4b60: 20 6c 69 6b 65 6c 79 28 29 20 73 75 72 72 6f 75   likely() surrou
4b70: 6e 64 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e  nds.** a boolean
4b80: 20 65 78 70 72 65 73 73 69 6f 6e 20 74 68 61 74   expression that
4b90: 20 69 73 20 75 73 75 61 6c 6c 79 20 74 72 75 65   is usually true
4ba0: 2e 20 20 47 43 43 20 69 73 20 61 62 6c 65 20 74  .  GCC is able t
4bb0: 6f 0a 2a 2a 20 75 73 65 20 74 68 65 73 65 20 68  o.** use these h
4bc0: 69 6e 74 73 20 74 6f 20 67 65 6e 65 72 61 74 65  ints to generate
4bd0: 20 62 65 74 74 65 72 20 63 6f 64 65 2c 20 73 6f   better code, so
4be0: 6d 65 74 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 20  metimes..*/.#if 
4bf0: 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f  defined(__GNUC__
4c00: 29 20 26 26 20 30 0a 23 20 64 65 66 69 6e 65 20  ) && 0.# define 
4c10: 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 5f 5f 62  likely(X)    __b
4c20: 75 69 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 58  uiltin_expect((X
4c30: 29 2c 31 29 0a 23 20 64 65 66 69 6e 65 20 75 6e  ),1).# define un
4c40: 6c 69 6b 65 6c 79 28 58 29 20 20 5f 5f 62 75 69  likely(X)  __bui
4c50: 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 2c  ltin_expect((X),
4c60: 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  0).#else.# defin
4c70: 65 20 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 21  e likely(X)    !
4c80: 21 28 58 29 0a 23 20 64 65 66 69 6e 65 20 75 6e  !(X).# define un
4c90: 6c 69 6b 65 6c 79 28 58 29 20 20 21 21 28 58 29  likely(X)  !!(X)
4ca0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a  .#endif../******
4cb0: 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65  ******** Include
4cc0: 20 73 71 6c 69 74 65 33 2e 68 20 69 6e 20 74 68   sqlite3.h in th
4cd0: 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69  e middle of sqli
4ce0: 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a  teInt.h ********
4cf0: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  *******/./******
4d00: 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66  ******** Begin f
4d10: 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a  ile sqlite3.h **
4d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d40: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32  *******/./*.** 2
4d50: 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35  001 September 15
4d60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
4d70: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
4d80: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
4d90: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
4da0: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
4db0: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
4dc0: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
4dd0: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
4de0: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
4df0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
4e00: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
4e10: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
4e20: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
4e30: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
4e40: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
4e50: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
4e60: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
4e70: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
4e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ea0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4eb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
4ec0: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
4ed0: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
4ee0: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
4ef0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
4f00: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
4f10: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
4f20: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
4f30: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
4f40: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
4f50: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
4f60: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
4f70: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
4f80: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
4f90: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
4fa0: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
4fb0: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
4fc0: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
4fd0: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
4fe0: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
4ff0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
5000: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
5010: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
5020: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
5030: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
5040: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
5050: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
5060: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
5070: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
5080: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
5090: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
50a0: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
50b0: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
50c0: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
50d0: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
50e0: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
50f0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
5100: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
5110: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
5120: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
5130: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
5140: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
5150: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
5160: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
5170: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
5180: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
5190: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
51a0: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
51b0: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
51c0: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
51d0: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
51e0: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
51f0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
5200: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
5210: 72 65 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70  re suppose to op
5220: 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  erate..**.** The
5230: 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69   name of this fi
5240: 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75  le under configu
5250: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
5260: 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69  t is "sqlite.h.i
5270: 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66  n"..** The makef
5280: 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d  ile makes some m
5290: 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20  inor changes to 
52a0: 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 20  this file (such 
52b0: 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20  as inserting.** 
52c0: 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  the version numb
52d0: 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20  er) and changes 
52e0: 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c  its name to "sql
52f0: 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61  ite3.h" as.** pa
5300: 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20  rt of the build 
5310: 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e  process..*/.#ifn
5320: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  def _SQLITE3_H_.
5330: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33  #define _SQLITE3
5340: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74  _H_.#include <st
5350: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e  darg.h>     /* N
5360: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65  eeded for the de
5370: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c  finition of va_l
5380: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61  ist */../*.** Ma
5390: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63  ke sure we can c
53a0: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66  all this stuff f
53b0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20  rom C++..*/.#if 
53c0: 30 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23  0.extern "C" {.#
53d0: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64  endif.../*.** Ad
53e0: 64 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  d the ability to
53f0: 20 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72   override 'exter
5400: 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  n'.*/.#ifndef SQ
5410: 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65  LITE_EXTERN.# de
5420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45  fine SQLITE_EXTE
5430: 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66  RN extern.#endif
5440: 0a 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  ..#ifndef SQLITE
5450: 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51  _API.# define SQ
5460: 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a  LITE_API.#endif.
5470: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f  ../*.** These no
5480: 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75  -op macros are u
5490: 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20  sed in front of 
54a0: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61  interfaces to ma
54b0: 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65  rk those.** inte
54c0: 72 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72  rfaces as either
54d0: 20 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65   deprecated or e
54e0: 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65  xperimental.  Ne
54f0: 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  w applications.*
5500: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65  * should not use
5510: 20 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65   deprecated inte
5520: 72 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72  rfaces - they ar
5530: 65 20 73 75 70 70 6f 72 74 20 66 6f 72 20 62 61  e support for ba
5540: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
5550: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20  tibility only.  
5560: 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74  Application writ
5570: 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77  ers should be aw
5580: 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65  are that.** expe
5590: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
55a0: 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 20  ces are subject 
55b0: 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69  to change in poi
55c0: 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  nt releases..**.
55d0: 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20  ** These macros 
55e0: 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20  used to resolve 
55f0: 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73  to various kinds
5600: 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67   of compiler mag
5610: 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64  ic that.** would
5620: 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e   generate warnin
5630: 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20  g messages when 
5640: 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e 20  they were used. 
5650: 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d   But that.** com
5660: 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65  piler magic ende
5670: 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20  d up generating 
5680: 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66  such a flurry of
5690: 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20   bug reports.** 
56a0: 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61 6b  that we have tak
56b0: 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e  en it all out an
56c0: 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75  d gone back to u
56d0: 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e  sing simple.** n
56e0: 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23  oop macros..*/.#
56f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
5700: 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65  PRECATED.#define
5710: 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45   SQLITE_EXPERIME
5720: 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75  NTAL../*.** Ensu
5730: 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73  re these symbols
5740: 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65   were not define
5750: 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f  d by some previo
5760: 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a  us header file..
5770: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
5780: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
5790: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
57a0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
57b0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
57c0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
57d0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
57e0: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
57f0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
5800: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
5810: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a  ersion Numbers.*
5820: 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49  *.** ^(The [SQLI
5830: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 72  TE_VERSION] C pr
5840: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
5850: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e   in the sqlite3.
5860: 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c  h header.** eval
5870: 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 6e  uates to a strin
5880: 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69  g literal that i
5890: 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72  s the SQLite ver
58a0: 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66  sion in the.** f
58b0: 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 68  ormat "X.Y.Z" wh
58c0: 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 6a  ere X is the maj
58d0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
58e0: 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 0a  r (always 3 for.
58f0: 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 20  ** SQLite3) and 
5900: 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  Y is the minor v
5910: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
5920: 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 61  d Z is the relea
5930: 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20  se number.)^.** 
5940: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
5950: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20  RSION_NUMBER] C 
5960: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
5970: 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61  ro resolves to a
5980: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74  n integer.** wit
5990: 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31  h the value (X*1
59a0: 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20  000000 + Y*1000 
59b0: 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c  + Z) where X, Y,
59c0: 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 73   and Z are the s
59d0: 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75  ame.** numbers u
59e0: 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56  sed in [SQLITE_V
59f0: 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68  ERSION].)^.** Th
5a00: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
5a10: 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 20  _NUMBER for any 
5a20: 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f 66  given release of
5a30: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
5a40: 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 74  o.** be larger t
5a50: 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 20  han the release 
5a60: 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 73  from which it is
5a70: 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 65   derived.  Eithe
5a80: 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68  r Y will.** be h
5a90: 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64  eld constant and
5aa0: 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65   Z will be incre
5ab0: 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 59  mented or else Y
5ac0: 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65   will be increme
5ad0: 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69  nted.** and Z wi
5ae0: 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 7a  ll be reset to z
5af0: 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65  ero..**.** Since
5b00: 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c   version 3.6.18,
5b10: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
5b20: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
5b30: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
5b40: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
5b50: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
5b60: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
5b70: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
5b80: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
5b90: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
5ba0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
5bb0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
5bc0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
5bd0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
5be0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
5bf0: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
5c00: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
5c10: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
5c20: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
5c30: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
5c40: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
5c50: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
5c60: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
5c70: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e  -in (UTC) and an
5c80: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
5c90: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
5ca0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
5cb0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
5cc0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
5cd0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
5ce0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
5cf0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
5d00: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
5d10: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
5d20: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
5d30: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
5d40: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
5d50: 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 37 2e 31  ON        "3.7.1
5d60: 36 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  6".#define SQLIT
5d70: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
5d80: 20 33 30 30 37 30 31 36 0a 23 64 65 66 69 6e 65   3007016.#define
5d90: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
5da0: 44 20 20 20 20 20 20 22 32 30 31 33 2d 30 33 2d  D      "2013-03-
5db0: 30 36 20 31 31 3a 34 34 3a 35 37 20 36 36 35 37  06 11:44:57 6657
5dc0: 36 62 34 35 30 61 30 66 30 33 32 39 35 37 31 65  6b450a0f0329571e
5dd0: 33 34 34 32 38 30 39 39 34 61 39 36 34 63 39 36  344280994a964c96
5de0: 37 66 38 66 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  7f8f"../*.** CAP
5df0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
5e00: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
5e10: 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f  Numbers.** KEYWO
5e20: 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72  RDS: sqlite3_ver
5e30: 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f  sion, sqlite3_so
5e40: 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65  urceid.**.** The
5e50: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72  se interfaces pr
5e60: 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69  ovide the same i
5e70: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68  nformation as th
5e80: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  e [SQLITE_VERSIO
5e90: 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56  N],.** [SQLITE_V
5ea0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20  ERSION_NUMBER], 
5eb0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  and [SQLITE_SOUR
5ec0: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
5ed0: 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20  essor macros.** 
5ee0: 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74  but are associat
5ef0: 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72  ed with the libr
5f00: 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ary instead of t
5f10: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20  he header file. 
5f20: 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70   ^(Cautious.** p
5f30: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
5f40: 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28   include assert(
5f50: 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  ) statements in 
5f60: 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f  their applicatio
5f70: 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74  n to.** verify t
5f80: 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72  hat values retur
5f90: 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74  ned by these int
5fa0: 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68  erfaces match th
5fb0: 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74  e macros in.** t
5fc0: 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74  he header, and t
5fd0: 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20  hus insure that 
5fe0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
5ff0: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
6000: 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62  ith matching lib
6010: 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20  rary and header 
6020: 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c  files..**.** <bl
6030: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
6040: 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65  * assert( sqlite
6050: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
6060: 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45  ber()==SQLITE_VE
6070: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a  RSION_NUMBER );.
6080: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
6090: 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  p(sqlite3_source
60a0: 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52  id(),SQLITE_SOUR
60b0: 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20  CE_ID)==0 );.** 
60c0: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
60d0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
60e0: 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49  n(),SQLITE_VERSI
60f0: 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70  ON)==0 );.** </p
6100: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
6110: 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
6120: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20  lite3_version[] 
6130: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
6140: 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78  contains the tex
6150: 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52  t of [SQLITE_VER
6160: 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20  SION].** macro. 
6170: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69   ^The sqlite3_li
6180: 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74  bversion() funct
6190: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ion returns a po
61a0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
61b0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  to the sqlite3_v
61c0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
61d0: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73  constant.  The s
61e0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
61f0: 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  n().** function 
6200: 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  is provided for 
6210: 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63  use in DLLs sinc
6220: 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61  e DLL users usua
6230: 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a  lly do not have.
6240: 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73  ** direct access
6250: 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74   to string const
6260: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20  ants within the 
6270: 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  DLL.  ^The.** sq
6280: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
6290: 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69  _number() functi
62a0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  on returns an in
62b0: 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a  teger equal to.*
62c0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
62d0: 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65  N_NUMBER].  ^The
62e0: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
62f0: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  d() function ret
6300: 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  urns .** a point
6310: 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63  er to a string c
6320: 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61  onstant whose va
6330: 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  lue is the same 
6340: 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  as the .** [SQLI
6350: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
6360: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
6370: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ro..**.** See al
6380: 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73  so: [sqlite_vers
6390: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
63a0: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e  te_source_id()].
63b0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
63c0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
63d0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51  3_version[] = SQ
63e0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51  LITE_VERSION;.SQ
63f0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
6400: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
6410: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
6420: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
6430: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
6440: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
6450: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
6460: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
6470: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
6480: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
6490: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
64a0: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
64b0: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
64c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
64d0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
64e0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
64f0: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
6500: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
6510: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
6520: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
6530: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
6540: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
6550: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
6560: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
6570: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
6580: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
6590: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
65a0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
65b0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
65c0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
65d0: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
65e0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
65f0: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
6600: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
6610: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
6620: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
6630: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
6640: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
6650: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
6660: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
6670: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
6680: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
6690: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
66a0: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
66b0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
66c0: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
66d0: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
66e0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
66f0: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
6700: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
6710: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
6720: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
6730: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
6740: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
6750: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
6760: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
6770: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6780: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
6790: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
67a0: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
67b0: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
67c0: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
67d0: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
67e0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
67f0: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
6800: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
6810: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
6820: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
6830: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
6840: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
6850: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
6860: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
6870: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
6880: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
6890: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
68a0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
68b0: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74  ption_used(const
68c0: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29   char *zOptName)
68d0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
68e0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
68f0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6900: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
6910: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
6920: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
6930: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
6940: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
6950: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
6960: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
6970: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
6980: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
6990: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
69a0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
69b0: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74  exing code omitt
69c0: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a  ed due to the.**
69d0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
69e0: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AFE] compile-tim
69f0: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73  e option being s
6a00: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53  et to 0..**.** S
6a10: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d  QLite can be com
6a20: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69  piled with or wi
6a30: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20  thout mutexes.  
6a40: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  When.** the [SQL
6a50: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
6a60: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
6a70: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20  acro is 1 or 2, 
6a80: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
6a90: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74  nabled and SQLit
6aa0: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e  e is threadsafe.
6ab0: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53    When the.** [S
6ac0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
6ad0: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a  ] macro is 0, .*
6ae0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
6af0: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
6b00: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
6b10: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
6b20: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
6b30: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72   concurrently fr
6b40: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  om more than one
6b50: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45   thread..**.** E
6b60: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20  nabling mutexes 
6b70: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61  incurs a measura
6b80: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ble performance 
6b90: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69  penalty..** So i
6ba0: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74  f speed is of ut
6bb0: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c  most importance,
6bc0: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20   it makes sense 
6bd0: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  to disable.** th
6be0: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20  e mutexes.  But 
6bf0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65  for maximum safe
6c00: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ty, mutexes shou
6c10: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  ld be enabled..*
6c20: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
6c30: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
6c40: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
6c50: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
6c60: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
6c70: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70  e used by an app
6c80: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65  lication to make
6c90: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a   sure that the.*
6ca0: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
6cb0: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c  ite that it is l
6cc0: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77  inking against w
6cd0: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
6ce0: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20  .** the desired 
6cf0: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b  setting of the [
6d00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
6d10: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  E] macro..**.** 
6d20: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f  This interface o
6d30: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74  nly reports on t
6d40: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
6d50: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a  mutex setting.**
6d60: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
6d70: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67  THREADSAFE] flag
6d80: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
6d90: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
6da0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
6db0: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20  FE=1 or =2 then 
6dc0: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
6dd0: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
6de0: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
6df0: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
6e00: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
6e10: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
6e20: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
6e30: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
6e40: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
6e50: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
6e60: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
6e70: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
6e80: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
6e90: 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74  TEX].  ^(The ret
6ea0: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
6eb0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65  .** sqlite3_thre
6ec0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
6ed0: 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65  n shows only the
6ee0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65   compile-time se
6ef0: 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65  tting of.** thre
6f00: 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61  ad safety, not a
6f10: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e  ny run-time chan
6f20: 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74  ges to that sett
6f30: 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73  ing made by.** s
6f40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
6f50: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
6f60: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
6f70: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74  e from sqlite3_t
6f80: 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69  hreadsafe().** i
6f90: 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63  s unchanged by c
6fa0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
6fb0: 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a  config().)^.**.*
6fc0: 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61  * See the [threa
6fd0: 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d  ding mode] docum
6fe0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
6ff0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
7000: 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
7010: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
7020: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
7030: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7040: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
7050: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20  ction Handle.** 
7060: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62  KEYWORDS: {datab
7070: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20  ase connection} 
7080: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
7090: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  tions}.**.** Eac
70a0: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
70b0: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
70c0: 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74  ented by a point
70d0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
70e0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71  e of.** the opaq
70f0: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d  ue structure nam
7100: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49  ed "sqlite3".  I
7110: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74  t is useful to t
7120: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74  hink of an sqlit
7130: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73  e3.** pointer as
7140: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65   an object.  The
7150: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
7160: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
7170: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  16()], and.** [s
7180: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
7190: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ] interfaces are
71a0: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
71b0: 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  s, and [sqlite3_
71c0: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20  close()].** and 
71d0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
71e0: 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 73  2()] are its des
71f0: 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65  tructors.  There
7200: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a   are many other.
7210: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 73  ** interfaces (s
7220: 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74  uch as.** [sqlit
7230: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
7240: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
7250: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
7260: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
7270: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
7280: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
7290: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
72a0: 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ds on an.** sqli
72b0: 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74  te3 object..*/.t
72c0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
72d0: 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a  lite3 sqlite3;..
72e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
72f0: 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54  64-Bit Integer T
7300: 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
7310: 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  : sqlite_int64 s
7320: 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a  qlite_uint64.**.
7330: 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65  ** Because there
7340: 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61   is no cross-pla
7350: 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65  tform way to spe
7360: 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65  cify 64-bit inte
7370: 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c  ger types.** SQL
7380: 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70  ite includes typ
7390: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
73a0: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
73b0: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
73c0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
73d0: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
73e0: 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68  e3_uint64 are th
73f0: 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65  e preferred type
7400: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a   definitions..**
7410: 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36   The sqlite_int6
7420: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
7430: 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75  t64 types are su
7440: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
7450: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
7460: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  bility only..**.
7470: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
7480: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
7490: 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  _int64 types can
74a0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
74b0: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
74c0: 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37   -92233720368547
74d0: 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33  75808 and +92233
74e0: 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69  72036854775807 i
74f0: 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a  nclusive.  ^The.
7500: 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  ** sqlite3_uint6
7510: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
7520: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
7530: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
7540: 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  es .** between 0
7550: 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37   and +1844674407
7560: 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75  3709551615 inclu
7570: 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  sive..*/.#ifdef 
7580: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
7590: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
75a0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
75b0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
75c0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
75d0: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
75e0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
75f0: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
7600: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
7610: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
7620: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
7630: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
7640: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
7650: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
7660: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
7670: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
7680: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
7690: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
76a0: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
76b0: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
76c0: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
76d0: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
76e0: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
76f0: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
7700: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
7710: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
7720: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
7730: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
7740: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
7750: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
7760: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
7770: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
7780: 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64  g-point..*/.#ifd
7790: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
77a0: 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
77b0: 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71  define double sq
77c0: 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64  lite3_int64.#end
77d0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
77e0: 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61  EF: Closing A Da
77f0: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
7800: 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
7810: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
7820: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
7830: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
7840: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
7850: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7860: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
7870: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
7880: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
7890: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
78a0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
78b0: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
78c0: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
78d0: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
78e0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
78f0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
7900: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
7910: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
7920: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
7930: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
7940: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
7950: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
7960: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
7970: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
7980: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
7990: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
79a0: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
79b0: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
79c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
79d0: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
79e0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
79f0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
7a00: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
7a10: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
7a20: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
7a30: 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69  ents.** and unfi
7a40: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
7a50: 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65  ackups, then the
7a60: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7a70: 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20  tion becomes.** 
7a80: 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d  an unusable "zom
7a90: 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20  bie" which will 
7aa0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65  automatically be
7ab0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65   deallocated whe
7ac0: 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72  n the.** last pr
7ad0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
7ae0: 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72   is finalized or
7af0: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
7b00: 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66  3_backup is.** f
7b10: 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71  inished.  The sq
7b20: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
7b30: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
7b40: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77  tended for use w
7b50: 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67  ith.** host lang
7b60: 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67  uages that are g
7b70: 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64  arbage collected
7b80: 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20  , and where the 
7b90: 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a  order in which.*
7ba0: 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72  * destructors ar
7bb0: 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69  e called is arbi
7bc0: 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  trary..**.** App
7bd0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
7be0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
7bf0: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
7c00: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
7c10: 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71  tements],.** [sq
7c20: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
7c30: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
7c40: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e  LOB handles], an
7c50: 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  d .** [sqlite3_b
7c60: 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66  ackup_finish | f
7c70: 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69  inish] all [sqli
7c80: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
7c90: 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  cts associated.*
7ca0: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  * with the [sqli
7cb0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f  te3] object prio
7cc0: 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20  r to attempting 
7cd0: 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a  to close the obj
7ce0: 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c  ect.  ^If.** sql
7cf0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69 73 20  ite3_close() is 
7d00: 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74  called on a [dat
7d10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7d20: 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73  ] that still has
7d30: 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  .** outstanding 
7d40: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
7d50: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
7d60: 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  dles], and/or.**
7d70: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
7d80: 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 69  ] objects then i
7d90: 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  t returns SQLITE
7da0: 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65 61 6c  _OK but the deal
7db0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72  location.** of r
7dc0: 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65  esources is defe
7dd0: 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b  rred until all [
7de0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
7df0: 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64  nts], [BLOB hand
7e00: 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71  les],.** and [sq
7e10: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
7e20: 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64  jects are also d
7e30: 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20  estroyed..**.** 
7e40: 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d  ^If an [sqlite3]
7e50: 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72   object is destr
7e60: 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61  oyed while a tra
7e70: 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nsaction is open
7e80: 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63  ,.** the transac
7e90: 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69  tion is automati
7ea0: 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
7eb0: 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70  k..**.** The C p
7ec0: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
7ed0: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61  ite3_close(C)] a
7ee0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
7ef0: 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74  e_v2(C)].** must
7f00: 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c   be either a NUL
7f10: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20  L.** pointer or 
7f20: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
7f30: 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61  ect pointer obta
7f40: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
7f50: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
7f60: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
7f70: 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
7f80: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
7f90: 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79  d not previously
7fa0: 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c   closed..** ^Cal
7fb0: 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ling sqlite3_clo
7fc0: 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  se() or sqlite3_
7fd0: 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20  close_v2() with 
7fe0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
7ff0: 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  * argument is a 
8000: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
8010: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
8020: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  t sqlite3_close(
8030: 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
8040: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
8050: 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74  3_close_v2(sqlit
8060: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  e3*);../*.** The
8070: 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c   type for a call
8080: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  back function..*
8090: 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79  * This is legacy
80a0: 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e   and deprecated.
80b0: 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64    It is included
80c0: 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a   for historical.
80d0: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
80e0: 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75   and is not docu
80f0: 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64  mented..*/.typed
8100: 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33  ef int (*sqlite3
8110: 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  _callback)(void*
8120: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61  ,int,char**, cha
8130: 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  r**);../*.** CAP
8140: 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20  I3REF: One-Step 
8150: 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20  Query Execution 
8160: 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20  Interface.**.** 
8170: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
8180: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
8190: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
81a0: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
81b0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
81c0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
81d0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
81e0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
81f0: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
8200: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
8210: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
8220: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
8230: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
8240: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
8250: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
8260: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
8270: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
8280: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
8290: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
82a0: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
82b0: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
82c0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
82d0: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
82e0: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
82f0: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
8300: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
8310: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
8320: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
8330: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
8340: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
8350: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
8360: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
8370: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
8380: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
8390: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
83a0: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
83b0: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
83c0: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
83d0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
83e0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
83f0: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
8400: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
8410: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
8420: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
8430: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
8440: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
8450: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
8460: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
8470: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
8480: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
8490: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
84a0: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
84b0: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
84c0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
84d0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
84e0: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
84f0: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
8500: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
8510: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
8520: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
8530: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
8540: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
8550: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
8560: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
8570: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
8580: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
8590: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
85a0: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
85b0: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
85c0: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
85d0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
85e0: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
85f0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
8600: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
8610: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
8620: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
8630: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
8640: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
8650: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
8660: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
8670: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
8680: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
8690: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
86a0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
86b0: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f  arameter of.** o
86c0: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
86d0: 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   after the error
86e0: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
86f0: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65  is no longer nee
8700: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ded..** ^If the 
8710: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
8720: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8730: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
8740: 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63  no errors.** occ
8750: 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ur, then sqlite3
8760: 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65  _exec() sets the
8770: 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20   pointer in its 
8780: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
8790: 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20  .** NULL before 
87a0: 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
87b0: 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f   ^If an sqlite3_
87c0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
87d0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
87e0: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  , the sqlite3_ex
87f0: 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  ec().** routine 
8800: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41  returns SQLITE_A
8810: 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76  BORT without inv
8820: 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61  oking the callba
8830: 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20  ck again and.** 
8840: 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20  without running 
8850: 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53  any subsequent S
8860: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
8870: 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72  *.** ^The 2nd ar
8880: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
8890: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
88a0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69  lback function i
88b0: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
88c0: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
88d0: 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20  e result.  ^The 
88e0: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  3rd argument to 
88f0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
8900: 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ().** callback i
8910: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
8920: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
8930: 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66  s obtained as if
8940: 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
8950: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
8960: 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63  , one for each c
8970: 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65  olumn.  ^If an e
8980: 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72  lement of a.** r
8990: 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c  esult row is NUL
89a0: 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65  L then the corre
89b0: 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20  sponding string 
89c0: 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a  pointer for the.
89d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
89e0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  ) callback is a 
89f0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
8a00: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
8a10: 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   to the.** sqlit
8a20: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
8a30: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
8a40: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
8a50: 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68  rings where each
8a60: 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73  .** entry repres
8a70: 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ents the name of
8a80: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72   corresponding r
8a90: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20  esult column as 
8aa0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
8ab0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
8ac0: 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _name()]..**.** 
8ad0: 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61  ^If the 2nd para
8ae0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
8af0: 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c  _exec() is a NUL
8b00: 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69  L pointer, a poi
8b10: 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d  nter.** to an em
8b20: 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61  pty string, or a
8b30: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f   pointer that co
8b40: 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74  ntains only whit
8b50: 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a  espace and/or .*
8b60: 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20  * SQL comments, 
8b70: 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74  then no SQL stat
8b80: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
8b90: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74  ated and the dat
8ba0: 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20  abase.** is not 
8bb0: 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  changed..**.** R
8bc0: 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a  estrictions:.**.
8bd0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
8be0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
8bf0: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
8c00: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
8c10: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
8c20: 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20  ec().**      is 
8c30: 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e  a valid and open
8c40: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
8c50: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  ction]..** <li> 
8c60: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
8c70: 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b  must not close [
8c80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
8c90: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
8ca0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
8cb0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
8cc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
8cd0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
8ce0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
8cf0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
8d00: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
8d10: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
8d20: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
8d30: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
8d40: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
8d50: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
8d60: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
8d70: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
8d80: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
8d90: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
8da0: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
8db0: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
8dc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8dd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
8de0: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
8df0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
8e00: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
8e10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8e20: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
8e30: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
8e40: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
8e50: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
8e60: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
8e70: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
8e80: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
8e90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8ea0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
8eb0: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
8ec0: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
8ed0: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
8ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8ef0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
8f00: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
8f10: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
8f20: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
8f30: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
8f40: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
8f50: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
8f60: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
8f70: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
8f80: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
8f90: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
8fa0: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
8fb0: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
8fc0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
8fd0: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
8fe0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
8ff0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
9000: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
9010: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
9020: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
9030: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
9040: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
9050: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
9060: 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  : [SQLITE_IOERR_
9070: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
9080: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a  result codes],.*
9090: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  * [sqlite3_vtab_
90a0: 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b  on_conflict()] [
90b0: 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20  SQLITE_ROLLBACK 
90c0: 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e  | result codes].
90d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
90e0: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
90f0: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
9100: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
9110: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
9120: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
9130: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
9140: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
9150: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
9160: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
9170: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
9180: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
9190: 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63  * Internal logic
91a0: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65   error in SQLite
91b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
91c0: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20  TE_PERM         
91d0: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65  3   /* Access pe
91e0: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20  rmission denied 
91f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9200: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34  E_ABORT        4
9210: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72     /* Callback r
9220: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64  outine requested
9230: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65   an abort */.#de
9240: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
9250: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20           5   /* 
9260: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  The database fil
9270: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
9280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
9290: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f  CKED       6   /
92a0: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65  * A table in the
92b0: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63   database is loc
92c0: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
92d0: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20  QLITE_NOMEM     
92e0: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c     7   /* A mall
92f0: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23  oc() failed */.#
9300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
9310: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f  ADONLY     8   /
9320: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69  * Attempt to wri
9330: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61  te a readonly da
9340: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
9350: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  e SQLITE_INTERRU
9360: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65  PT    9   /* Ope
9370: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65  ration terminate
9380: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74  d by sqlite3_int
9390: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69  errupt()*/.#defi
93a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  ne SQLITE_IOERR 
93b0: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f        10   /* So
93c0: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20  me kind of disk 
93d0: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72  I/O error occurr
93e0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
93f0: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20  LITE_CORRUPT    
9400: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74   11   /* The dat
9410: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65  abase disk image
9420: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f   is malformed */
9430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9440: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20  NOTFOUND    12  
9450: 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f   /* Unknown opco
9460: 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69  de in sqlite3_fi
9470: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a  le_control() */.
9480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
9490: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
94a0: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
94b0: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
94c0: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
94d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
94e0: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
94f0: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
9500: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
9510: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
9520: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
9530: 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61    15   /* Databa
9540: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
9550: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
9560: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
9570: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
9580: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
9590: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
95a0: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
95b0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
95c0: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
95d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
95e0: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
95f0: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
9600: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
9610: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
9620: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
9630: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
9640: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
9650: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
9660: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
9670: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
9680: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
9690: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
96a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
96b0: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
96c0: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
96d0: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
96e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
96f0: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
9700: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
9710: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
9720: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
9730: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
9740: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
9750: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
9760: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
9770: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
9780: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
9790: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
97a0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
97b0: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
97c0: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
97d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
97e0: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
97f0: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
9800: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
9810: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
9820: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
9830: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
9840: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
9850: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
9860: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
9870: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
9880: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
9890: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
98a0: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
98b0: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
98c0: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
98d0: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
98e0: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
98f0: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
9900: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
9910: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
9920: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
9930: 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
9940: 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72  e} {extended err
9950: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
9960: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
9970: 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65   result code} {e
9980: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
9990: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  odes}.**.** In i
99a0: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
99b0: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
99c0: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
99d0: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69  turn one of 26 i
99e0: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
99f0: 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
9a00: 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20  des].  However, 
9a10: 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73  experience has s
9a20: 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f  hown that many o
9a30: 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c  f.** these resul
9a40: 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20  t codes are too 
9a50: 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20  coarse-grained. 
9a60: 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f   They do not pro
9a70: 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20  vide as.** much 
9a80: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
9a90: 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72  t problems as pr
9aa0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
9ab0: 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66  like.  In an eff
9ac0: 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73  ort to.** addres
9ad0: 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65  s this, newer ve
9ae0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
9af0: 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20   (version 3.3.8 
9b00: 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75  and later) inclu
9b10: 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f  de.** support fo
9b20: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73  r additional res
9b30: 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70  ult codes that p
9b40: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
9b50: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
9b60: 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73  .** about errors
9b70: 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72  . The extended r
9b80: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
9b90: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
9ba0: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
9bb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9bc0: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
9bd0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
9be0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
9bf0: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a  codes()] API..**
9c00: 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20  .** Some of the 
9c10: 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64  available extend
9c20: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
9c30: 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e  are listed here.
9c40: 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65  .** One may expe
9c50: 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ct the number of
9c60: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
9c70: 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65   codes will be e
9c80: 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69  xpand.** over ti
9c90: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
9ca0: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
9cb0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
9cc0: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
9cd0: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
9ce0: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
9cf0: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
9d00: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
9d10: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
9d20: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
9d30: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
9d40: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
9d50: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
9d60: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
9d70: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
9d80: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
9d90: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
9da0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9db0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
9dc0: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
9dd0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
9de0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
9df0: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
9e00: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
9e10: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
9e20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9e30: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
9e40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9e50: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
9e60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
9e70: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
9e80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
9e90: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
9ea0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9eb0: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
9ec0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9ed0: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
9ee0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9ef0: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
9f00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9f10: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
9f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
9f30: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
9f40: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
9f50: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
9f60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
9f70: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
9f80: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
9f90: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
9fa0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
9fb0: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
9fc0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
9fd0: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
9fe0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
9ff0: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
a000: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
a010: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
a020: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
a030: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
a040: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
a050: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
a060: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
a070: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
a080: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
a090: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
a0a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
a0b0: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
a0c0: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
a0d0: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
a0e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
a0f0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
a100: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
a110: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
a120: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
a130: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
a140: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
a150: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
a160: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
a170: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
a180: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
a190: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
a1a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
a1b0: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
a1c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
a1d0: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
a1e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
a1f0: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
a200: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
a210: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
a220: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
a230: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
a240: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
a250: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
a260: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
a270: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
a280: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
a290: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
a2a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
a2b0: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
a2c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
a2d0: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
a2e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
a2f0: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
a300: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
a310: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
a320: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
a330: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
a340: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
a350: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
a360: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
a370: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
a380: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
a390: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
a3a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
a3b0: 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20  OPEN_NOTEMPDIR  
a3c0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
a3d0: 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OPEN | (1<<8)).#
a3e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
a3f0: 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20  NTOPEN_ISDIR    
a400: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
a410: 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29  NTOPEN | (2<<8))
a420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a430: 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54  CANTOPEN_FULLPAT
a440: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
a450: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38  CANTOPEN | (3<<8
a460: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a470: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
a480: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
a490: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
a4a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
a4b0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
a4c0: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
a4d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
a4e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
a4f0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
a500: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
a510: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
a520: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
a530: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
a540: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28  ROLLBACK       (
a550: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
a560: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
a570: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
a580: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
a590: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
a5a0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
a5b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
a5c0: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
a5d0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
a5e0: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
a5f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
a600: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
a610: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
a620: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
a630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a640: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
a650: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
a660: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
a670: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
a680: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
a690: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
a6a0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
a6b0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
a6c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
a6d0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
a6e0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
a6f0: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
a700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
a710: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
a720: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
a730: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
a740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a750: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
a760: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
a770: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
a780: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
a790: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
a7a0: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
a7b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
a7c0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
a7d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
a7e0: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
a7f0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
a800: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 0a 2f 2a  NT | (9<<8))../*
a810: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
a820: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
a830: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
a840: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
a850: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
a860: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
a870: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
a880: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
a890: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
a8a0: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
a8b0: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
a8c0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
a8d0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
a8e0: 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  hod..*/.#define 
a8f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
a900: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
a910: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66  0000001  /* Ok f
a920: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
a930: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
a940: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
a950: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
a960: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66  0000002  /* Ok f
a970: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
a980: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
a990: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
a9a0: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
a9b0: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66  0000004  /* Ok f
a9c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
a9d0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
a9e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
a9f0: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
aa00: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20  0000008  /* VFS 
aa10: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
aa20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
aa30: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
aa40: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20  0000010  /* VFS 
aa50: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
aa60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f  SQLITE_OPEN_AUTO
aa70: 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30  PROXY        0x0
aa80: 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20  0000020  /* VFS 
aa90: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
aaa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
aab0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
aac0: 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66  0000040  /* Ok f
aad0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
aae0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
aaf0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f  SQLITE_OPEN_MEMO
ab00: 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30  RY           0x0
ab10: 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66  0000080  /* Ok f
ab20: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
ab30: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
ab40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
ab50: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
ab60: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20  0000100  /* VFS 
ab70: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
ab80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
ab90: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
aba0: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20  0000200  /* VFS 
abb0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
abc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
abd0: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
abe0: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20  0000400  /* VFS 
abf0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
ac00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
ac10: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
ac20: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20  0000800  /* VFS 
ac30: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
ac40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
ac50: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
ac60: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20  0001000  /* VFS 
ac70: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
ac80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
ac90: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
aca0: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20  0002000  /* VFS 
acb0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
acc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
acd0: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
ace0: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20  0004000  /* VFS 
acf0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
ad00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
ad10: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30  TEX          0x0
ad20: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0008000  /* Ok f
ad30: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
ad40: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
ad50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
ad60: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30  MUTEX        0x0
ad70: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0010000  /* Ok f
ad80: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
ad90: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
ada0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
adb0: 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30  EDCACHE      0x0
adc0: 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0020000  /* Ok f
add0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
ade0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
adf0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
ae00: 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30  ATECACHE     0x0
ae10: 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0040000  /* Ok f
ae20: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
ae30: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
ae40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20  SQLITE_OPEN_WAL 
ae50: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
ae60: 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20  0080000  /* VFS 
ae70: 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65  only */../* Rese
ae80: 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20  rved:           
ae90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
aea0: 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a  00F00000 */../*.
aeb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
aec0: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
aed0: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
aee0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
aef0: 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  tics method of t
af00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
af10: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
af20: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
af30: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
af40: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a  vector of these.
af50: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
af60: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
af70: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
af80: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
af90: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
afa0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
afb0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
afc0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
afd0: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
afe0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
aff0: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
b000: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
b010: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
b020: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
b030: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
b040: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
b050: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
b060: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
b070: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
b080: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
b090: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
b0a0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
b0b0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
b0c0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
b0d0: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
b0e0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
b0f0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
b100: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
b110: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
b120: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
b130: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
b140: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
b150: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
b160: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
b170: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
b180: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
b190: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
b1a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
b1b0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
b1c0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
b1d0: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
b1e0: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
b1f0: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
b200: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
b210: 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c  rite().  The SQL
b220: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
b230: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72  AFE_OVERWRITE pr
b240: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
b250: 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f  t.** after reboo
b260: 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  t following a cr
b270: 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73  ash or power los
b280: 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65  s, the only byte
b290: 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74  s in a.** file t
b2a0: 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e  hat were written
b2b0: 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74   at the applicat
b2c0: 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20  ion level might 
b2d0: 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  have changed.** 
b2e0: 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e  and that adjacen
b2f0: 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79  t bytes, even by
b300: 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  tes within the s
b310: 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a  ame sector are.*
b320: 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  * guaranteed to 
b330: 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f  be unchanged..*/
b340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b350: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
b360: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
b370: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
b380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
b390: 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20  MIC512          
b3a0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
b3b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
b3c0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20  CAP_ATOMIC1K    
b3d0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
b3e0: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
b3f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
b400: 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C2K             
b410: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
b420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
b430: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20  P_ATOMIC4K      
b440: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
b450: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
b460: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
b470: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
b480: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
b490: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
b4a0: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
b4b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
b4c0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b4d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
b4e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
b4f0: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65  00000080.#define
b500: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
b510: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20  OMIC64K         
b520: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
b530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
b540: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
b550: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
b560: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
b570: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
b580: 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20  ENTIAL          
b590: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64     0x00000400.#d
b5a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
b5b0: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
b5c0: 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30  HEN_OPEN  0x0000
b5d0: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
b5e0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
b5f0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
b600: 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a   0x00001000../*.
b610: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
b620: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
b630: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
b640: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
b650: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
b660: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
b670: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
b680: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
b690: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
b6a0: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
b6b0: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
b6c0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
b6d0: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
b6e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
b6f0: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
b700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
b710: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
b720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b730: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
b740: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
b750: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
b760: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
b770: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
b780: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
b790: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
b7a0: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
b7b0: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
b7c0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
b7d0: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
b7e0: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
b7f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
b800: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
b810: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
b820: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
b830: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
b840: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
b850: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
b860: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
b870: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
b880: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
b890: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
b8a0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
b8b0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
b8c0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
b8d0: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
b8e0: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
b8f0: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
b900: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
b910: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
b920: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
b930: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
b940: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
b950: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
b960: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
b970: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
b980: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
b990: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
b9a0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
b9b0: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
b9c0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
b9d0: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
b9e0: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
b9f0: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
ba00: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
ba10: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
ba20: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
ba30: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
ba40: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
ba50: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
ba60: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
ba70: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
ba80: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
ba90: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
baa0: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
bab0: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
bac0: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
bad0: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
bae0: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
baf0: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
bb00: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
bb10: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
bb20: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
bb30: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
bb40: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
bb50: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
bb60: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
bb70: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
bb80: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
bb90: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
bba0: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
bbb0: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
bbc0: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
bbd0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
bbe0: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
bbf0: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
bc00: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
bc10: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
bc20: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
bc30: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
bc40: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
bc50: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
bc60: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
bc70: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
bc80: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
bc90: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
bca0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
bcb0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
bcc0: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
bcd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
bce0: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
bcf0: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
bd00: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
bd10: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
bd20: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
bd30: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
bd40: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
bd50: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
bd60: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
bd70: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
bd80: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
bd90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
bda0: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
bdb0: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
bdc0: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
bdd0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
bde0: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
bdf0: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
be00: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
be10: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
be20: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
be30: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
be40: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
be50: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
be60: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
be70: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
be80: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
be90: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
bea0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
beb0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
bec0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
bed0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
bee0: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
bef0: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
bf00: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
bf10: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
bf20: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
bf30: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
bf40: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
bf50: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
bf60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
bf70: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
bf80: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
bf90: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
bfa0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
bfb0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
bfc0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
bfd0: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
bfe0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
bff0: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
c000: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
c010: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
c020: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
c030: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
c040: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
c050: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
c060: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
c070: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
c080: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
c090: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
c0a0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
c0b0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
c0c0: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
c0d0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
c0e0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
c0f0: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
c100: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
c110: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
c120: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
c130: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
c140: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
c150: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
c160: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
c170: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
c180: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
c190: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
c1a0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
c1b0: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
c1c0: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
c1d0: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
c1e0: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
c1f0: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
c200: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
c210: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
c220: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
c230: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
c240: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
c250: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
c260: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
c270: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
c280: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
c290: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
c2a0: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
c2b0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
c2c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
c2d0: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
c2e0: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
c2f0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
c300: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
c310: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
c320: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
c330: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
c340: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
c350: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
c360: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
c370: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
c380: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
c390: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
c3a0: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
c3b0: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
c3c0: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
c3d0: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
c3e0: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
c3f0: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
c400: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c410: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
c420: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
c430: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
c440: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
c450: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
c460: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
c470: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
c480: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
c490: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
c4a0: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
c4b0: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
c4c0: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
c4d0: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
c4e0: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
c4f0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
c500: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
c510: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
c520: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
c530: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
c540: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
c550: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
c560: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
c570: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
c580: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
c590: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
c5a0: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
c5b0: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
c5c0: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
c5d0: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
c5e0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
c5f0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
c600: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
c610: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
c620: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
c630: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
c640: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
c650: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
c660: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
c670: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
c680: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
c690: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
c6a0: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
c6b0: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
c6c0: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
c6d0: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
c6e0: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
c6f0: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
c700: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
c710: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
c720: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
c730: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
c740: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
c750: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
c760: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
c770: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
c780: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
c790: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
c7a0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
c7b0: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
c7c0: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
c7d0: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
c7e0: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
c7f0: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
c800: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
c810: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
c820: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
c830: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
c840: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
c850: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
c860: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
c870: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
c880: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
c890: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
c8a0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
c8b0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
c8c0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
c8d0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
c8e0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
c8f0: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
c900: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
c910: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
c920: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
c930: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
c940: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
c950: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
c960: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
c970: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
c980: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
c990: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
c9a0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
c9b0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
c9c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
c9d0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
c9e0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
c9f0: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
ca00: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
ca10: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
ca20: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
ca30: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
ca40: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
ca50: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
ca60: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
ca70: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
ca80: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
ca90: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
caa0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
cab0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
cac0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
cad0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
cae0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
caf0: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
cb00: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
cb10: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
cb20: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
cb30: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
cb40: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
cb50: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
cb60: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
cb70: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
cb80: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
cb90: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
cba0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
cbb0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
cbc0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
cbd0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
cbe0: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
cbf0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
cc00: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
cc10: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
cc20: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
cc30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
cc40: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
cc50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
cc60: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
cc70: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
cc80: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
cc90: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
cca0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
ccb0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
ccc0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
ccd0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
cce0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
ccf0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
cd00: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
cd10: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
cd20: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
cd30: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
cd40: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
cd50: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
cd60: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
cd70: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
cd80: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
cd90: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
cda0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
cdb0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
cdc0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
cdd0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
cde0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
cdf0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
ce00: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
ce10: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
ce20: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
ce30: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
ce40: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
ce50: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
ce60: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
ce70: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
ce80: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
ce90: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
cea0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
ceb0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
cec0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
ced0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
cee0: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
cef0: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
cf00: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
cf10: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
cf20: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
cf30: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
cf40: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
cf50: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
cf60: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
cf70: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
cf80: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
cf90: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
cfa0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
cfb0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
cfc0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
cfd0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
cfe0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
cff0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
d000: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
d010: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d020: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
d030: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
d040: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
d050: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
d060: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
d070: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
d080: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
d090: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
d0a0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
d0b0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
d0c0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
d0d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
d0e0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
d0f0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
d100: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
d110: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
d120: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
d130: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
d140: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
d150: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
d160: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
d170: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
d180: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
d190: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
d1a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
d1b0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
d1c0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
d1d0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
d1e0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
d1f0: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
d200: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
d210: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
d220: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
d230: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
d240: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
d250: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
d260: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
d270: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
d280: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
d290: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
d2a0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
d2b0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
d2c0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
d2d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
d2e0: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
d2f0: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
d300: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
d310: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
d320: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
d330: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
d340: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
d350: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
d360: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
d370: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
d380: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
d390: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
d3a0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
d3b0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
d3c0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
d3d0: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
d3e0: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
d3f0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
d400: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
d410: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
d420: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
d430: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a  trol Opcodes.**.
d440: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
d450: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f   constants are o
d460: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78  pcodes for the x
d470: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
d480: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  od.** of the [sq
d490: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d4a0: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72  ] object and for
d4b0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
d4c0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a  le_control()].**
d4d0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
d4e0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
d4f0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
d500: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
d510: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
d520: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
d530: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
d540: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
d550: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
d560: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
d570: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
d580: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
d590: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
d5a0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
d5b0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
d5c0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
d5d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
d5e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
d5f0: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
d600: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
d610: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
d620: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
d630: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
d640: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
d650: 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  ting and only ne
d660: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
d670: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
d680: 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e  TEST.** is defin
d690: 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ed..** <ul>.** <
d6a0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
d6b0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a  L_SIZE_HINT]].**
d6c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
d6d0: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70  TL_SIZE_HINT] op
d6e0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20  code is used by 
d6f0: 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74  SQLite to give t
d700: 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20  he VFS.** layer 
d710: 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61  a hint of how la
d720: 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  rge the database
d730: 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20   file will grow 
d740: 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65  to be during the
d750: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e  .** current tran
d760: 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68  saction.  This h
d770: 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61  int is not guara
d780: 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75  nteed to be accu
d790: 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69  rate but it.** i
d7a0: 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20  s often close.  
d7b0: 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56  The underlying V
d7c0: 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20  FS might choose 
d7d0: 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64  to preallocate d
d7e0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
d7f0: 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74  space based on t
d800: 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65  his hint in orde
d810: 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73  r to help writes
d820: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
d830: 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73  .** file run fas
d840: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
d850: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
d860: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  UNK_SIZE]].** Th
d870: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
d880: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
d890: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
d8a0: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
d8b0: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
d8c0: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
d8d0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
d8e0: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
d8f0: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
d900: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
d910: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
d920: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
d930: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
d940: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
d950: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
d960: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
d970: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
d980: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
d990: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
d9a0: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
d9b0: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
d9c0: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
d9d0: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
d9e0: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
d9f0: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
da00: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
da10: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
da20: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
da30: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
da40: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
da50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
da60: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
da70: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
da80: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  ILE_POINTER] opc
da90: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
daa0: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
dab0: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
dac0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
dad0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
dae0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
daf0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
db00: 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73  ion.  See the [s
db10: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
db20: 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61  rol()] documenta
db30: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69  tion for.** addi
db40: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
db50: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  on..**.** <li>[[
db60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
db70: 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e  C_OMITTED]].** ^
db80: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  (The [SQLITE_FCN
db90: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
dba0: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
dbb0: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
dbc0: 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64  by.** SQLite and
dbd0: 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53   sent to all VFS
dbe0: 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61  es in place of a
dbf0: 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79   call to the xSy
dc00: 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65  nc method.** whe
dc10: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
dc20: 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50  onnection has [P
dc30: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
dc40: 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e  s] set to OFF.)^
dc50: 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c  .** Some special
dc60: 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20  ized VFSes need 
dc70: 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f  this signal in o
dc80: 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20  rder to operate 
dc90: 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65  correctly.** whe
dca0: 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  n [PRAGMA synchr
dcb0: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73  onous | PRAGMA s
dcc0: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20  ynchronous=OFF] 
dcd0: 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74  is set, but most
dce0: 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f   .** VFSes do no
dcf0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
dd00: 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69  al and should si
dd10: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
dd20: 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70  is opcode..** Ap
dd30: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
dd40: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
dd50: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
dd60: 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a  ()] with this.**
dd70: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
dd80: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
dd90: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  the operation of
dda0: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
ddb0: 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64   VFSes.** that d
ddc0: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
ddd0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
dde0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
ddf0: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
de00: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
de10: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
de20: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
de30: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
de40: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
de50: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
de60: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
de70: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
de80: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
de90: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
dea0: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
deb0: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
dec0: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
ded0: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
dee0: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
def0: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
df00: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
df10: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
df20: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
df30: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
df40: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
df50: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
df60: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
df70: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
df80: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
df90: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
dfa0: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
dfb0: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
dfc0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
dfd0: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
dfe0: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
dff0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
e000: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
e010: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
e020: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
e030: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
e040: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
e050: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
e060: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
e070: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e080: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
e090: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
e0a0: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
e0b0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
e0c0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
e0d0: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
e0e0: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
e0f0: 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65  ger i the new re
e100: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
e110: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
e120: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
e130: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
e140: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
e150: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
e160: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
e170: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
e180: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
e190: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
e1a0: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
e1b0: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
e1c0: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
e1d0: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
e1e0: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
e1f0: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
e200: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
e210: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
e220: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
e230: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
e240: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
e250: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
e260: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
e270: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
e280: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
e290: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
e2a0: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64  AL | Write Ahead
e2b0: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
e2c0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
e2d0: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
e2e0: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64  te ahead log and
e2f0: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
e300: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
e310: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
e320: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
e330: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
e340: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
e350: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
e360: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
e370: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
e380: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
e390: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
e3a0: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
e3b0: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
e3c0: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
e3d0: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
e3e0: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
e3f0: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
e400: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
e410: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
e420: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
e430: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
e440: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
e450: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
e460: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
e470: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
e480: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
e490: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
e4a0: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
e4b0: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
e4c0: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
e4d0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
e4e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
e4f0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
e500: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
e510: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
e520: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
e530: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
e540: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
e550: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
e560: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
e570: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
e580: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
e590: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
e5a0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
e5b0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
e5c0: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
e5d0: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
e5e0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
e5f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
e600: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
e610: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
e620: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
e630: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
e640: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
e650: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
e660: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
e670: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
e680: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
e690: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
e6a0: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
e6b0: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
e6c0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
e6d0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
e6e0: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
e6f0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
e700: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
e710: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
e720: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
e730: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
e740: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
e750: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
e760: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
e770: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
e780: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
e790: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
e7a0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
e7b0: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
e7c0: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
e7d0: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
e7e0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
e7f0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
e800: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
e810: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
e820: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
e830: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
e840: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
e850: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
e860: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
e870: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
e880: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
e890: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
e8a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
e8b0: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
e8c0: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
e8d0: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
e8e0: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
e8f0: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
e900: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
e910: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
e920: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
e930: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
e940: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
e950: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
e960: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
e970: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
e980: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
e990: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
e9a0: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
e9b0: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
e9c0: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
e9d0: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
e9e0: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
e9f0: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
ea00: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
ea10: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
ea20: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
ea30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
ea40: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
ea50: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
ea60: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
ea70: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
ea80: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
ea90: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
eaa0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
eab0: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
eac0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
ead0: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
eae0: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
eaf0: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
eb00: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
eb10: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
eb20: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
eb30: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
eb40: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
eb50: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
eb60: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
eb70: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
eb80: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
eb90: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
eba0: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
ebb0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
ebc0: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
ebd0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
ebe0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
ebf0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
ec00: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
ec10: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
ec20: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
ec30: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ec40: 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57  L_PRAGMA]].** ^W
ec50: 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d  henever a [PRAGM
ec60: 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  A] statement is 
ec70: 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49  parsed, an [SQLI
ec80: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
ec90: 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f   .** file contro
eca0: 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65  l is sent to the
ecb0: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   open [sqlite3_f
ecc0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72  ile] object corr
ecd0: 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20  esponding.** to 
ece0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
ecf0: 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70  e to which the p
ed00: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
ed10: 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67  refers. ^The arg
ed20: 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
ed30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ed40: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ed50: 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ol is an array o
ed60: 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  f.** pointers to
ed70: 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a   strings (char**
ed80: 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73  ) in which the s
ed90: 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66  econd element of
eda0: 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73   the array.** is
edb0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
edc0: 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20   pragma and the 
edd0: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73  third element is
ede0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
edf0: 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f   the.** pragma o
ee00: 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72  r NULL if the pr
ee10: 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75  agma has no argu
ee20: 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64  ment.  ^The hand
ee30: 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53  ler for an.** [S
ee40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ee50: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
ee60: 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   can optionally 
ee70: 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65  make the first e
ee80: 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65  lement.** of the
ee90: 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74   char** argument
eea0: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
eeb0: 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
eec0: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
eed0: 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65  f()].** or the e
eee0: 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68  quivalent and th
eef0: 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  at string will b
ef00: 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74  ecome the result
ef10: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f   of the pragma o
ef20: 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  r.** the error m
ef30: 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72  essage if the pr
ef40: 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20  agma fails. ^If 
ef50: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
ef60: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ef70: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
ef80: 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  s [SQLITE_NOTFOU
ef90: 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c  ND], then normal
efa0: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72   .** [PRAGMA] pr
efb0: 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75  ocessing continu
efc0: 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  es.  ^If the [SQ
efd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
efe0: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
eff0: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
f000: 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65  TE_OK], then the
f010: 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20   parser assumes 
f020: 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20  that the.** VFS 
f030: 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20  has handled the 
f040: 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e  PRAGMA itself an
f050: 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e  d the parser gen
f060: 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a  erates a no-op.*
f070: 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
f080: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b  ment.  ^If the [
f090: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
f0a0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
f0b0: 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  l returns.** any
f0c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68   result code oth
f0d0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
f0e0: 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  OK] or [SQLITE_N
f0f0: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d  OTFOUND], that m
f100: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  eans.** that the
f110: 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64   VFS encountered
f120: 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20   an error while 
f130: 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52  handling the [PR
f140: 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  AGMA] and the.**
f150: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20   compilation of 
f160: 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73  the PRAGMA fails
f170: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
f180: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
f190: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
f1a0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75  ile control occu
f1b0: 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e  rs at the beginn
f1c0: 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74  ing of pragma st
f1d0: 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73  atement analysis
f1e0: 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73   and so.** it is
f1f0: 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64   able to overrid
f200: 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47  e built-in [PRAG
f210: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  MA] statements..
f220: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
f230: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
f240: 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 69 73 20  DLER]].** ^This 
f250: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79  file-control may
f260: 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   be invoked by S
f270: 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74  QLite on the dat
f280: 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c  abase file handl
f290: 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74  e.** shortly aft
f2a0: 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20  er it is opened 
f2b0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
f2c0: 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53  ide a custom VFS
f2d0: 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20   with access.** 
f2e0: 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  to the connectio
f2f0: 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  ns busy-handler 
f300: 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72  callback. The ar
f310: 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70  gument is of typ
f320: 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d  e (void **).** -
f330: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
f340: 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73   (void *) values
f350: 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69  . The first (voi
f360: 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f  d *) actually po
f370: 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e  ints.** to a fun
f380: 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69  ction of type (i
f390: 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e  nt (*)(void *)).
f3a0: 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76   In order to inv
f3b0: 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  oke the connecti
f3c0: 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64  ons.** busy-hand
f3d0: 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ler, this functi
f3e0: 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76  on should be inv
f3f0: 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65  oked with the se
f400: 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e  cond (void *) in
f410: 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73  .** the array as
f420: 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65   the only argume
f430: 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  nt. If it return
f440: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
f450: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
f460: 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72  * should be retr
f470: 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72  ied. If it retur
f480: 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73  ns zero, the cus
f490: 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61  tom VFS should a
f4a0: 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75  bandon the.** cu
f4b0: 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e  rrent operation.
f4c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
f4d0: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
f4e0: 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70  LENAME]].** ^App
f4f0: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76  lication can inv
f500: 6f 6b 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  oke this file-co
f510: 6e 74 72 6f 6c 20 74 6f 20 68 61 76 65 20 53 51  ntrol to have SQ
f520: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
f530: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
f540: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
f550: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
f560: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
f570: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
f580: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
f590: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
f5a0: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
f5b0: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
f5c0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
f5d0: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
f5e0: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
f5f0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
f600: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
f610: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
f620: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
f630: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
f640: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
f650: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
f660: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
f670: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
f680: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
f690: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ak..**.** </ul>.
f6a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f6b0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
f6c0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
f6d0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
f6e0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
f6f0: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32  LE             2
f700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f710: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
f720: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a  E             3.
f730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
f740: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
f750: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
f760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
f770: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
f780: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
f790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
f7a0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
f7b0: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
f7c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
f7d0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
f7e0: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
f7f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
f800: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
f810: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
f820: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
f830: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
f840: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
f850: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
f860: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
f870: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
f880: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
f890: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
f8a0: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
f8b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
f8c0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
f8d0: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
f8e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
f8f0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
f900: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
f910: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
f920: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
f930: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
f940: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
f950: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
f960: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
f970: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
f980: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
f990: 31 36 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  16../*.** CAPI3R
f9a0: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
f9b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
f9c0: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
f9d0: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
f9e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
f9f0: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
fa00: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
fa10: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
fa20: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
fa30: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
fa40: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
fa50: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
fa60: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
fa70: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
fa80: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
fa90: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
faa0: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
fab0: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
fac0: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
fad0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
fae0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
faf0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
fb00: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
fb10: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
fb20: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
fb30: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
fb40: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
fb50: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
fb60: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
fb70: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
fb80: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
fb90: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
fba0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
fbb0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
fbc0: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
fbd0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
fbe0: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
fbf0: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
fc00: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a   system".  See.*
fc10: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53  * the [VFS | VFS
fc20: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
fc30: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f  for further info
fc40: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
fc50: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
fc60: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69  iVersion field i
fc70: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75  s initially 1 bu
fc80: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20  t may be larger 
fc90: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72  in.** future ver
fca0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
fcb0: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65    Additional fie
fcc0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
fcd0: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f  ded to this.** o
fce0: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69  bject when the i
fcf0: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73  Version value is
fd00: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74   increased.  Not
fd10: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
fd20: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
fd30: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
fd40: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
fd50: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74   transaction bet
fd60: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76  ween.** SQLite v
fd70: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64  ersion 3.5.9 and
fd80: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74   3.6.0 and yet t
fd90: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
fda0: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64  d was not.** mod
fdb0: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ified..**.** The
fdc0: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20   szOsFile field 
fdd0: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
fde0: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73  he subclassed [s
fdf0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20  qlite3_file].** 
fe00: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62  structure used b
fe10: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50  y this VFS.  mxP
fe20: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d  athname is the m
fe30: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
fe40: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69  .** a pathname i
fe50: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a  n this VFS..**.*
fe60: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c  * Registered sql
fe70: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73  ite3_vfs objects
fe80: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c   are kept on a l
fe90: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65  inked list forme
fea0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78  d by.** the pNex
feb0: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  t pointer.  The 
fec0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
fed0: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20  ister()].** and 
fee0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
fef0: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
ff00: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69  faces manage thi
ff10: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74  s list.** in a t
ff20: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20  hread-safe way. 
ff30: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
ff40: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66  s_find()] interf
ff50: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20  ace.** searches 
ff60: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68  the list.  Neith
ff70: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
ff80: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20  on code nor the 
ff90: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  VFS.** implement
ffa0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ation should use
ffb0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
ffc0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  er..**.** The pN
ffd0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
ffe0: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74   only field in t
fff0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
10000 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
10010 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
10020 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
10030 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
10040 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
10050 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65  this field while
10060 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69   holding a parti
10070 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74  cular static mut
10080 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ex..** The appli
10090 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
100a0 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68  ver modify anyth
100b0 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73  ing within the s
100c0 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
100d0 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
100e0 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
100f0 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  gistered..**.** 
10100 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20  The zName field 
10110 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f  holds the name o
10120 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65  f the VFS module
10130 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  .  The name must
10140 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63  .** be unique ac
10150 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64  ross all VFS mod
10160 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  ules..**.** [[sq
10170 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
10180 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ].** ^SQLite gua
10190 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
101a0 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
101b0 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a  eter to xOpen.**
101c0 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c   is either a NUL
101d0 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72  L pointer or str
101e0 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ing obtained.** 
101f0 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61  from xFullPathna
10200 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74  me() with an opt
10210 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64  ional suffix add
10220 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66  ed..** ^If a suf
10230 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20  fix is added to 
10240 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
10250 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c  rameter, it will
10260 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61  .** consist of a
10270 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72   single "-" char
10280 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62  acter followed b
10290 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a  y no more than.*
102a0 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69  * 11 alphanumeri
102b0 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61  c and/or "-" cha
102c0 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c  racters..** ^SQL
102d0 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
102e0 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
102f0 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
10300 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
10310 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
10320 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
10330 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
10340 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
10350 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nce,.** the [sql
10360 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
10370 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
10380 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
10390 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
103a0 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
103b0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
103c0 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
103d0 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
103e0 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
103f0 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
10400 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
10410 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e  en.** must inven
10420 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  t its own tempor
10430 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
10440 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65   file.  ^Wheneve
10450 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
10460 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
10470 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
10480 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
10490 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
104a0 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
104b0 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
104c0 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
104d0 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
104e0 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
104f0 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
10500 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
10510 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
10520 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
10530 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
10540 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
10550 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
10560 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
10570 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
10580 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
10590 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
105a0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
105b0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
105c0 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
105d0 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
105e0 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
105f0 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
10600 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
10610 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
10620 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
10630 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
10640 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
10650 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  et..**.** ^(SQLi
10660 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
10670 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
10680 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
10690 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
106a0 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
106b0 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
106c0 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
106d0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
106e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
106f0 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
10700 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
10710 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
10720 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
10730 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
10740 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
10750 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
10760 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
10770 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
10780 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
10790 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
107a0 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
107b0 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
107c0 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
107d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c  [SQLITE_OPEN_WAL
107e0 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ].** </ul>)^.**.
107f0 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
10800 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
10810 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
10820 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
10830 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
10840 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
10850 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
10860 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
10870 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
10880 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
10890 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
108a0 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
108b0 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
108c0 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
108d0 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
108e0 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
108f0 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
10900 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
10910 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
10920 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
10930 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
10940 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
10950 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
10960 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
10970 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
10980 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
10990 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
109a0 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
109b0 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
109c0 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
109d0 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
109e0 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
109f0 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
10a00 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
10a10 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
10a20 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
10a30 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
10a40 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
10a50 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
10a60 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
10a70 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
10a80 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
10a90 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
10aa0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
10ab0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
10ac0 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
10ad0 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
10ae0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
10af0 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
10b00 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51  losed.  ^The [SQ
10b10 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
10b20 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
10b30 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
10b40 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74   databases and t
10b50 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74  heir journals, t
10b60 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61  ransient.** data
10b70 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f  bases, and subjo
10b80 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  urnals..**.** ^T
10b90 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
10ba0 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
10bb0 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
10bc0 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
10bd0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
10be0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
10bf0 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
10c00 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
10c10 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
10c20 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
10c30 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
10c40 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
10c50 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
10c60 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
10c70 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
10c80 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
10c90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
10ca0 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
10cb0 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
10cc0 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
10cd0 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
10ce0 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
10cf0 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
10d00 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
10d10 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
10d20 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
10d30 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
10d40 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
10d50 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
10d60 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20  cess..**.** ^At 
10d70 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
10d80 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
10d90 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
10da0 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
10db0 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
10dc0 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
10dd0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
10de0 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
10df0 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
10e00 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
10e10 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
10e20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
10e30 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
10e40 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
10e50 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a  n.  Note that.**
10e60 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
10e70 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73  d must set the s
10e80 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
10e90 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  hods to either.*
10ea0 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74  * a valid [sqlit
10eb0 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
10ec0 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c  bject or to NULL
10ed0 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f  .  xOpen must do
10ee0 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66  .** this even if
10ef0 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e   the open fails.
10f00 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73    SQLite expects
10f10 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65   that the sqlite
10f20 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a  3_file.pMethods.
10f30 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20  ** element will 
10f40 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78  be valid after x
10f50 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67  Open returns reg
10f60 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
10f70 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69  uccess.** or fai
10f80 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65  lure of the xOpe
10f90 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  n call..**.** [[
10fa0 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63  sqlite3_vfs.xAcc
10fb0 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c  ess]].** ^The fl
10fc0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
10fd0 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
10fe0 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
10ff0 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
11000 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
11010 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
11020 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
11030 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
11040 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
11050 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
11060 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
11070 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
11080 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
11090 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
110a0 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
110b0 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
110c0 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
110d0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
110e0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c   ^SQLite will al
110f0 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
11100 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
11110 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
11120 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
11130 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
11140 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
11150 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
11160 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
11170 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
11180 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
11190 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
111a0 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
111b0 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
111c0 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
111d0 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
111e0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
111f0 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
11200 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
11210 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
11220 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
11230 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
11240 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
11250 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
11260 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
11270 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
11280 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
11290 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
112a0 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
112b0 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c   xCurrentTime(),
112c0 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
112d0 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65  eInt64().** inte
112e0 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73  rfaces are not s
112f0 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
11300 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
11310 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
11320 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
11330 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
11340 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
11350 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
11360 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
11370 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
11380 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
11390 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
113a0 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
113b0 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
113c0 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
113d0 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
113e0 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
113f0 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
11400 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65  ed..** The xSlee
11410 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
11420 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
11430 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
11440 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
11450 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
11460 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
11470 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
11480 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
11490 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
114a0 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
114b0 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
114c0 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61  and time as.** a
114d0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
114e0 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78  value..** ^The x
114f0 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
11500 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
11510 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  s, as an integer
11520 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20  , the Julian.** 
11530 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69  Day Number multi
11540 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30  plied by 8640000
11550 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  0 (the number of
11560 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e   milliseconds in
11570 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64   .** a 24-hour d
11580 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74  ay).  .** ^SQLit
11590 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78  e will use the x
115a0 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
115b0 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74  () method to get
115c0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
115d0 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66  date and time if
115e0 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20   that method is 
115f0 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56  available (if iV
11600 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a  ersion is 2 or .
11610 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74  ** greater and t
11620 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
11630 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29  ter is not NULL)
11640 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62   and will fall b
11650 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65  ack.** to xCurre
11660 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72  ntTime() if xCur
11670 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
11680 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
11690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53  **.** ^The xSetS
116a0 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65  ystemCall(), xGe
116b0 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61  tSystemCall(), a
116c0 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61  nd xNestSystemCa
116d0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  ll() interfaces.
116e0 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20  ** are not used 
116f0 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  by the SQLite co
11700 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f  re.  These optio
11710 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  nal interfaces a
11720 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62  re provided.** b
11730 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20  y some VFSes to 
11740 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69  facilitate testi
11750 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f  ng of the VFS co
11760 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e  de. By overridin
11770 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c  g .** system cal
11780 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e  ls with function
11790 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74  s under its cont
117a0 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67  rol, a test prog
117b0 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c  ram can.** simul
117c0 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65  ate faults and e
117d0 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20  rror conditions 
117e0 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72  that would other
117f0 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c  wise be difficul
11800 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62  t.** or impossib
11810 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54  le to induce.  T
11820 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d  he set of system
11830 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20   calls that can 
11840 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a  be overridden.**
11850 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65   varies from one
11860 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c   VFS to another,
11870 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65   and from one ve
11880 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d  rsion of the sam
11890 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20  e VFS to the.** 
118a0 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
118b0 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65  ons that use the
118c0 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75  se interfaces mu
118d0 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66  st be prepared f
118e0 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c  or any.** or all
118f0 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66   of these interf
11900 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20  aces to be NULL 
11910 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68  or for their beh
11920 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a  avior to change.
11930 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65  ** from one rele
11940 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ase to the next.
11950 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d    Applications m
11960 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20  ust not attempt 
11970 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79  to access.** any
11980 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64   of these method
11990 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f  s if the iVersio
119a0 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20  n of the VFS is 
119b0 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a  less than 3..*/.
119c0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
119d0 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
119e0 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20  e3_vfs;.typedef 
119f0 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73  void (*sqlite3_s
11a00 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64  yscall_ptr)(void
11a10 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  );.struct sqlite
11a20 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
11a30 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
11a40 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
11a50 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
11a60 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a  currently 3) */.
11a70 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
11a80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
11a90 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
11aa0 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
11ab0 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
11ac0 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
11ad0 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
11ae0 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
11af0 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
11b00 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
11b10 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
11b20 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
11b30 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
11b40 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
11b50 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
11b60 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
11b70 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
11b80 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
11b90 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
11ba0 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
11bb0 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
11bc0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
11bd0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
11be0 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
11bf0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
11c00 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
11c10 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
11c20 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
11c30 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
11c40 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
11c50 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
11c60 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
11c70 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
11c80 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
11c90 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
11ca0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
11cb0 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
11cc0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
11cd0 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
11ce0 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
11cf0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
11d00 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
11d10 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
11d20 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
11d30 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
11d40 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
11d50 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
11d60 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
11d70 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
11d80 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
11d90 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
11da0 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
11db0 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
11dc0 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
11dd0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
11de0 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
11df0 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
11e00 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
11e10 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
11e20 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
11e30 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
11e40 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
11e50 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
11e60 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
11e70 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
11e80 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
11e90 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
11ea0 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
11eb0 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
11ec0 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20  in version 1 of 
11ed0 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
11ee0 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e  bject.  ** defin
11ef0 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68  ition.  Those th
11f00 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64  at follow are ad
11f10 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32  ded in version 2
11f20 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20   or later.  */. 
11f30 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
11f40 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65  imeInt64)(sqlite
11f50 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f  3_vfs*, sqlite3_
11f60 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20  int64*);.  /*.  
11f70 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
11f80 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
11f90 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20  ions 1 and 2 of 
11fa0 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
11fb0 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73  bject..  ** Thos
11fc0 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20  e below are for 
11fd0 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72  version 3 and gr
11fe0 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e  eater..  */.  in
11ff0 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61  t (*xSetSystemCa
12000 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
12010 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
12020 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73  ame, sqlite3_sys
12030 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c  call_ptr);.  sql
12040 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
12050 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c   (*xGetSystemCal
12060 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
12070 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
12080 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61  me);.  const cha
12090 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d  r *(*xNextSystem
120a0 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
120b0 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
120c0 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a  zName);.  /*.  *
120d0 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
120e0 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
120f0 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20  ons 1 through 3 
12100 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
12110 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e  s object..  ** N
12120 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
12130 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
12140 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
12150 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
12160 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
12170 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
12180 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20  his happens. .  
12190 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
121a0 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
121b0 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
121c0 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
121d0 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
121e0 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
121f0 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
12200 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
12210 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
12220 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
12230 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
12240 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
12250 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
12260 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
12270 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
12280 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
12290 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
122a0 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78  SS_EXISTS, the x
122b0 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
122c0 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77   simply checks w
122d0 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
122e0 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20  exists..** With 
122f0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
12300 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
12310 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
12320 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
12330 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72  e named director
12340 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  y is both readab
12350 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a  le and writable.
12360 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72  ** (in other wor
12370 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e  ds, if files can
12380 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76   be added, remov
12390 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20  ed, and renamed 
123a0 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69  within.** the di
123b0 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65  rectory)..** The
123c0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
123d0 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e  EADWRITE constan
123e0 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75  t is currently u
123f0 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a  sed only by the.
12400 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  ** [temp_store_d
12410 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
12420 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f  , though this co
12430 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20  uld change in a 
12440 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
12450 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  e of SQLite..** 
12460 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
12470 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63  SS_READ, the xAc
12480 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
12490 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
124a0 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
124b0 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  le.  The SQLITE_
124c0 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73  ACCESS_READ cons
124d0 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65  tant is.** curre
124e0 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f  ntly unused, tho
124f0 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20  ugh it might be 
12500 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65  used in a future
12510 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
12520 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
12530 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
12540 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
12550 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
12560 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20  S_READWRITE 1   
12570 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d  /* Used by PRAGM
12580 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72  A temp_store_dir
12590 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e  ectory */.#defin
125a0 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
125b0 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a  READ      2   /*
125c0 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a   Unused */../*.*
125d0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
125e0 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f  s for the xShmLo
125f0 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ck VFS method.**
12600 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
12610 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  r constants defi
12620 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  ne the various l
12630 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e  ocking operation
12640 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20  s.** allowed by 
12650 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  the xShmLock met
12660 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  hod of [sqlite3_
12670 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68  io_methods].  Th
12680 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  e.** following a
12690 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61  re the only lega
126a0 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f  l combinations o
126b0 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a  f flags to the.*
126c0 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  * xShmLock metho
126d0 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
126e0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
126f0 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
12700 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
12710 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
12720 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
12730 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c  _EXCLUSIVE.** <l
12740 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
12750 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
12760 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
12770 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
12780 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
12790 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
127a0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  /ul>.**.** When 
127b0 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73  unlocking, the s
127c0 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58  ame SHARED or EX
127d0 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73  CLUSIVE flag mus
127e0 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73  t be supplied as
127f0 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f  .** was given no
12800 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
12810 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a  ng lock.  .**.**
12820 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
12830 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74  thod can transit
12840 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  ion between unlo
12850 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20  cked and SHARED 
12860 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e  or.** between un
12870 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55  locked and EXCLU
12880 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74  SIVE.  It cannot
12890 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
128a0 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e  een SHARED.** an
128b0 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a  d EXCLUSIVE..*/.
128c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
128d0 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  HM_UNLOCK       
128e0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
128f0 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20  _SHM_LOCK       
12900 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
12910 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20  TE_SHM_SHARED   
12920 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
12930 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
12940 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43  VE    8../*.** C
12950 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d  API3REF: Maximum
12960 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a   xShmLock index.
12970 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
12980 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71  ck method on [sq
12990 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
129a0 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73  ] may use values
129b0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
129c0 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75  d this upper bou
129d0 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65  nd as its "offse
129e0 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  t" argument..** 
129f0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
12a00 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d  will never attem
12a10 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72  pt to acquire or
12a20 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f   release a.** lo
12a30 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  ck outside of th
12a40 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66  is range.*/.#def
12a50 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e  ine SQLITE_SHM_N
12a60 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a  LOCK        8...
12a70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12a80 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
12a90 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
12aa0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
12ab0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
12ac0 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65  utine initialize
12ad0 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  s the.** SQLite 
12ae0 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73  library.  ^The s
12af0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12b00 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
12b10 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
12b20 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
12b30 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
12b40 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12b50 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ()..** These rou
12b60 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e  tines are design
12b70 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f  ed to aid in pro
12b80 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
12b90 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64  ion and.** shutd
12ba0 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20  own on embedded 
12bb0 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74  systems.  Workst
12bc0 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f  ation applicatio
12bd0 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69  ns using.** SQLi
12be0 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e  te normally do n
12bf0 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b  ot need to invok
12c00 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73  e either of thes
12c10 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
12c20 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
12c30 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12c40 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
12c50 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
12c60 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
12c70 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
12c80 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
12c90 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
12ca0 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
12cb0 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
12cc0 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
12cd0 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
12ce0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
12cf0 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
12d00 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
12d10 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
12d20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63   ^(Only an effec
12d30 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
12d40 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12d50 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
12d60 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
12d70 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
12d80 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
12d90 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  o-ops.)^.**.** A
12da0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
12db0 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61  _shutdown() is a
12dc0 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
12dd0 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20  ll if it is the 
12de0 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f  first.** call to
12df0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
12e00 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61  n() since the la
12e10 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  st sqlite3_initi
12e20 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79  alize().  ^(Only
12e30 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65  .** an effective
12e40 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
12e50 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73  _shutdown() does
12e60 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a   any deinitializ
12e70 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74  ation..** All ot
12e80 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20  her valid calls 
12e90 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
12ea0 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65  own() are harmle
12eb0 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
12ec0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
12ed0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65  nitialize() inte
12ee0 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73  rface is threads
12ef0 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33  afe, but sqlite3
12f00 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69  _shutdown().** i
12f10 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69  s not.  The sqli
12f20 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
12f30 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e  nterface must on
12f40 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  ly be called fro
12f50 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68  m a.** single th
12f60 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20  read.  All open 
12f70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12f80 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63  tions] must be c
12f90 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a  losed and all.**
12fa0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65   other SQLite re
12fb0 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20  sources must be 
12fc0 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f  deallocated prio
12fd0 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  r to invoking.**
12fe0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
12ff0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  n()..**.** Among
13000 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e   other things, ^
13010 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
13020 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ze() will invoke
13030 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
13040 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
13050 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74  y, ^sqlite3_shut
13060 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69  down().** will i
13070 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
13080 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _end()..**.** ^T
13090 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
130a0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
130b0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
130c0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a  OK] on success..
130d0 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20  ** ^If for some 
130e0 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
130f0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
13100 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
13110 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
13120 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
13130 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
13140 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
13150 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
13160 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
13170 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
13180 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
13190 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
131a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
131b0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
131c0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
131d0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d   internally by m
131e0 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  any other.** SQL
131f0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  ite interfaces s
13200 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63  o that an applic
13210 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f  ation usually do
13220 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a  es not need to.*
13230 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
13240 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
13250 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61  rectly.  For exa
13260 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  mple, [sqlite3_o
13270 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20  pen()].** calls 
13280 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
13290 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69  ze() so the SQLi
132a0 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
132b0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
132c0 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  .** initialized 
132d0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70  when [sqlite3_op
132e0 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  en()] is called 
132f0 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65  if it has not be
13300 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20   initialized.** 
13310 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76  already.  ^Howev
13320 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
13330 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
13340 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
13350 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d  AUTOINIT].** com
13360 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13370 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
13380 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
13390 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
133a0 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
133b0 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
133c0 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
133d0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
133e0 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
133f0 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
13400 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
13410 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
13420 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
13430 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
13440 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
13450 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
13460 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
13470 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
13480 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
13490 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
134a0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
134b0 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
134c0 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
134d0 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
134e0 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
134f0 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
13500 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
13510 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
13520 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
13530 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
13540 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f  INIT] might beco
13550 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  me the.** defaul
13560 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f  t behavior in so
13570 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
13580 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
13590 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
135a0 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65  s_init() routine
135b0 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d   does operating-
135c0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a  system specific.
135d0 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ** initializatio
135e0 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
135f0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71  library.  The sq
13600 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
13610 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
13620 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73   the effect of s
13630 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
13640 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73  .  Typical tasks
13650 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79  .** performed by
13660 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
13670 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69  include allocati
13680 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69  on or deallocati
13690 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20  on.** of static 
136a0 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69  resources, initi
136b0 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f  alization of glo
136c0 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a  bal variables,.*
136d0 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64  * setting up a d
136e0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
136f0 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  vfs] module, or 
13700 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
13710 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
13720 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
13730 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
13740 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
13750 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
13760 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  er invoke either
13770 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
13780 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
13790 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74  _os_end() direct
137a0 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ly.  The applica
137b0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  tion should only
137c0 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
137d0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
137e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74  and sqlite3_shut
137f0 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c  down().  The sql
13800 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
13810 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  * interface is c
13820 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61  alled automatica
13830 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69  lly by sqlite3_i
13840 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a  nitialize() and.
13850 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ** sqlite3_os_en
13860 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79  d() is called by
13870 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
13880 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74  n().  Appropriat
13890 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
138a0 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33  ions for sqlite3
138b0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
138c0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
138d0 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74  ** are built int
138e0 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74  o SQLite when it
138f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
13900 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20   Unix, Windows, 
13910 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e  or OS/2..** When
13920 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20   [custom builds 
13930 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65  | built for othe
13940 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20  r platforms].** 
13950 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49  (using the [SQLI
13960 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63  TE_OS_OTHER=1] c
13970 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
13980 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69  ption) the appli
13990 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
139a0 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  ly a suitable im
139b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
139c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
139d0 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
139e0 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20  3_os_end().  An 
139f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
13a00 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  lied.** implemen
13a10 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
13a20 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73  3_os_init() or s
13a30 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
13a40 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b  ** must return [
13a50 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
13a60 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f  ccess and some o
13a70 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65  ther [error code
13a80 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72  ] upon.** failur
13a90 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
13aa0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69   int sqlite3_ini
13ab0 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53  tialize(void);.S
13ac0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
13ad0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
13ae0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
13af0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f   int sqlite3_os_
13b00 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49  init(void);.SQLI
13b10 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
13b20 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
13b30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13b40 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
13b50 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
13b60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
13b70 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
13b80 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
13b90 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
13ba0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
13bb0 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
13bc0 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
13bd0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
13be0 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
13bf0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
13c00 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
13c10 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
13c20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
13c30 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
13c40 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
13c50 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
13c60 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
13c70 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
13c80 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
13c90 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
13ca0 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
13cb0 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
13cc0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
13cd0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
13ce0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
13cf0 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
13d00 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72  on.** must insur
13d10 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20  e that no other 
13d20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
13d30 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79  s are invoked by
13d40 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64   other.** thread
13d50 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  s while sqlite3_
13d60 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e  config() is runn
13d70 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72  ing.  Furthermor
13d80 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e, sqlite3_confi
13d90 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  g().** may only 
13da0 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
13db0 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
13dc0 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
13dd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
13de0 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
13df0 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
13e00 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
13e10 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  n()]..** ^If sql
13e20 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
13e30 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
13e40 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
13e50 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a  e()] and before.
13e60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
13e70 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20  down()] then it 
13e80 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
13e90 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f  TE_MISUSE..** No
13ea0 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
13eb0 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t ^sqlite3_confi
13ec0 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
13ed0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
13ee0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
13ef0 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
13f00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
13f10 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
13f20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
13f30 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
13f40 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
13f50 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
13f60 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
13f70 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
13f80 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
13f90 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
13fa0 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
13fb0 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
13fc0 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
13fd0 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
13fe0 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61  n the [configura
13ff0 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
14000 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
14010 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
14020 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
14030 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
14040 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
14050 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
14060 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
14070 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
14080 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
14090 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
140a0 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
140b0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
140c0 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
140d0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
140e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
140f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
14100 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
14110 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
14120 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
14130 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
14140 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
14150 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
14160 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
14170 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
14180 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
14190 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
141a0 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
141b0 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
141c0 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
141d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
141e0 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
141f0 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
14200 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
14210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
14220 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
14230 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14240 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
14250 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
14260 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14270 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
14280 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
14290 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
142a0 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
142b0 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
142c0 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
142d0 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
142e0 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
142f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14300 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
14310 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
14320 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
14330 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
14340 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
14350 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
14360 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
14370 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
14380 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
14390 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
143a0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
143b0 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
143c0 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  sful..*/.SQLITE_
143d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
143e0 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
143f0 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
14400 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14410 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
14420 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
14430 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
14440 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
14450 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
14460 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
14470 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
14480 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
14490 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
144a0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
144b0 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
144c0 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
144d0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
144e0 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
144f0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
14500 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
14510 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
14520 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14530 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
14540 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
14550 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
14560 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14570 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
14580 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
14590 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
145a0 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
145b0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
145c0 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
145d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
145e0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
145f0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
14600 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
14610 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
14620 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
14630 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
14640 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
14650 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
14660 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
14670 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
14680 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
14690 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
146a0 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
146b0 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
146c0 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
146d0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
146e0 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
146f0 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
14700 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
14710 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
14720 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
14730 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
14740 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
14750 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
14760 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
14770 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
14780 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
14790 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
147a0 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
147b0 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
147c0 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
147d0 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
147e0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
147f0 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
14800 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
14810 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
14820 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
14830 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
14840 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
14850 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
14860 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
14870 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
14880 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
14890 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
148a0 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
148b0 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
148c0 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
148d0 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
148e0 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
148f0 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
14900 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
14910 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
14920 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
14930 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
14940 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
14950 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
14960 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
14970 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
14980 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
14990 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
149a0 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
149b0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
149c0 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
149d0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
149e0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
149f0 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
14a00 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
14a10 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
14a20 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
14a30 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
14a40 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
14a50 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
14a60 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
14a70 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
14a80 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
14a90 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
14aa0 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
14ab0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14ac0 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
14ad0 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
14ae0 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
14af0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
14b00 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
14b10 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
14b20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
14b30 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
14b40 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
14b50 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
14b60 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
14b70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
14b80 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
14b90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14ba0 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
14bb0 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
14bc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
14bd0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
14be0 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
14bf0 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
14c00 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
14c10 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
14c20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
14c30 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
14c40 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
14c50 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
14c60 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
14c70 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
14c80 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46  y allocator.  (F
14c90 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
14ca0 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
14cb0 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
14cc0 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
14cd0 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
14ce0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
14cf0 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
14d00 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
14d10 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
14d20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
14d30 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
14d40 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
14d50 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
14d60 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
14d70 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
14d80 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
14d90 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
14da0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
14db0 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
14dc0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
14dd0 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
14de0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
14df0 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
14e00 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
14e10 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
14e20 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
14e30 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
14e40 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
14e50 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
14e60 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
14e70 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
14e80 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
14e90 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
14ea0 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
14eb0 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
14ec0 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
14ed0 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
14ee0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
14ef0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
14f00 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
14f10 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
14f20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14f30 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
14f40 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
14f50 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
14f60 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
14f70 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
14f80 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
14f90 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
14fa0 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
14fb0 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
14fc0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
14fd0 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
14fe0 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
14ff0 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
15000 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
15010 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
15020 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
15030 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
15040 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
15050 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
15060 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
15070 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
15080 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
15090 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
150a0 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
150b0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
150c0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
150d0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
150e0 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
150f0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
15100 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
15110 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
15120 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
15130 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
15140 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
15150 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
15160 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
15170 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
15180 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
15190 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
151a0 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
151b0 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
151c0 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
151d0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
151e0 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
151f0 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
15200 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
15210 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
15220 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
15230 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
15240 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
15250 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
15260 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
15270 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
15280 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
15290 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
152a0 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
152b0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
152c0 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
152d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
152e0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
152f0 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
15300 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
15310 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
15320 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
15330 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
15340 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
15350 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
15360 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
15370 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
15380 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
15390 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
153a0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
153b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
153c0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
153d0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
153e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
153f0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
15400 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
15410 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
15420 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15430 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
15440 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
15450 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
15460 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
15470 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15480 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
15490 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
154a0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
154b0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
154c0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
154d0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
154e0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
154f0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
15500 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
15510 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
15520 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
15530 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
15540 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
15550 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
15560 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
15570 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15580 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
15590 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
155a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
155b0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
155c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
155d0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
155e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
155f0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
15600 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
15610 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
15620 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
15630 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
15640 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
15650 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
15660 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
15670 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
15680 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
15690 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
156a0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
156b0 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
156c0 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
156d0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
156e0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
156f0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
15700 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
15710 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
15720 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
15730 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
15740 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
15750 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
15760 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
15770 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
15780 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
15790 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
157a0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
157b0 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
157c0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
157d0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
157e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
157f0 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
15800 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
15810 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15820 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
15830 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
15840 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
15850 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
15860 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
15870 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
15880 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
15890 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
158a0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
158b0 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
158c0 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
158d0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
158e0 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
158f0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
15900 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
15910 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
15920 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
15930 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
15940 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
15950 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
15960 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
15970 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
15980 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
15990 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
159a0 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
159b0 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
159c0 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
159d0 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
159e0 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
159f0 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
15a00 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
15a10 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
15a20 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
15a30 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
15a40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
15a50 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
15a60 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
15a70 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15a80 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15a90 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
15aa0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
15ab0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15ac0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
15ad0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
15ae0 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
15af0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
15b00 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
15b10 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15b20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
15b30 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
15b40 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
15b50 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
15b60 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
15b70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15b80 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
15ba0 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
15bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
15bc0 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
15bd0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
15be0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
15bf0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
15c00 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
15c10 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
15c20 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
15c30 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
15c40 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
15c50 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
15c60 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
15c70 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
15c80 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
15c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15ca0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
15cb0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
15cc0 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
15cd0 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
15ce0 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
15cf0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
15d00 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
15d10 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
15d20 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
15d30 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
15d40 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
15d50 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
15d60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
15d70 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
15d80 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
15d90 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
15da0 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
15db0 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
15dc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15dd0 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
15de0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
15df0 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
15e00 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
15e10 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
15e20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
15e30 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
15e40 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
15e50 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
15e60 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
15e70 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15e80 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
15e90 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
15ea0 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
15eb0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
15ec0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
15ed0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
15ee0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
15ef0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
15f00 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
15f10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
15f20 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
15f30 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
15f40 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15f50 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
15f60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15f70 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
15f80 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
15f90 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15fa0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
15fb0 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
15fc0 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
15fd0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
15fe0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
15ff0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
16000 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
16010 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
16020 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
16030 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
16040 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
16050 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
16060 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
16070 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
16080 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
16090 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .)^ ^SQLite make
160a0 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69  s.** its own pri
160b0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
160c0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
160d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
160e0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a  hods] structure.
160f0 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73  ** before the [s
16100 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
16110 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f   call returns.</
16120 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16130 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
16140 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
16150 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
16160 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
16170 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
16180 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
16190 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
161a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
161b0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
161c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
161d0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
161e0 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
161f0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
16200 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
16210 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
16220 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
16230 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16240 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
16250 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
16260 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
16270 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
16280 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
16290 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
162a0 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
162b0 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
162c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
162d0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
162e0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
162f0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
16300 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16310 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
16320 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
16330 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
16340 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
16350 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
16360 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
16370 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c  ent of type int,
16380 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
16390 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77  a .** boolean, w
163a0 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
163b0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
163c0 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72  lection of memor
163d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a  y allocation .**
163e0 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
163f0 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
16400 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
16410 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74   are disabled, t
16420 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  he .** following
16430 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
16440 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
16450 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
16460 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
16470 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
16480 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
16490 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
164a0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
164b0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
164c0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
164d0 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  64()].**   <li> 
164e0 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
164f0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
16500 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
16510 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
16520 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
16530 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
16540 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
16550 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
16560 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
16570 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
16580 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
16590 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
165a0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
165b0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
165c0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
165d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
165e0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
165f0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
16600 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
16610 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
16620 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
16630 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
16640 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
16650 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
16660 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
16670 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
16680 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  s:  A pointer an
16690 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
166a0 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
166b0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
166c0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
166d0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
166e0 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
166f0 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
16700 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
16710 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
16720 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
16730 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
16740 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
16750 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
16760 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
16770 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  16..** The first
16780 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
16790 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
167a0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
167b0 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74   buffer.** of at
167c0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
167d0 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
167e0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
167f0 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77   no more than tw
16800 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  o scratch buffer
16810 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53  s per thread.  S
16820 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65  o.** N should be
16830 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68   set to twice th
16840 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d  e expected maxim
16850 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  um number of thr
16860 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  eads..** ^SQLite
16870 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
16880 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75  ire a scratch bu
16890 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
168a0 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
168b0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
168c0 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51  age size. ^If SQ
168d0 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
168e0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
168f0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
16900 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
16910 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
16920 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16930 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
16940 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
16950 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
16960 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
16970 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a  y needed.</dd>.*
16980 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16990 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
169a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
169b0 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
169c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
169d0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
169e0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
169f0 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
16a00 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
16a10 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
16a20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
16a30 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
16a40 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
16a50 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
16a60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73   configuration s
16a70 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
16a80 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  d if an applicat
16a90 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
16aa0 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
16ab0 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
16ac0 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49  d using the SQLI
16ad0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16ae0 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  2 option..** The
16af0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
16b00 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
16b10 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72  ption: A pointer
16b20 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   to 8-byte align
16b30 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
16b40 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
16b50 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
16b60 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
16b70 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
16b80 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
16b90 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
16ba0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
16bb0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
16bc0 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
16bd0 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
16be0 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20  and 32768) plus 
16bf0 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66  a little extra f
16c00 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
16c10 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61  header.  ^The pa
16c20 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69  ge header size i
16c30 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73  s 20 to 40 bytes
16c40 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a   depending on.**
16c50 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74   the host archit
16c60 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20  ecture.  ^It is 
16c70 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
16c80 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
16c90 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61  memory,.** to ma
16ca0 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74  ke sz a little t
16cb0 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66  oo large.  The f
16cc0 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
16cd0 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
16ce0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
16cf0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
16d00 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
16d10 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
16d20 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
16d30 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
16d40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
16d50 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a  o satisfy its.**
16d60 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f   memory needs fo
16d70 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61  r the first N pa
16d80 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73  ges that it adds
16d90 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20   to cache.  ^If 
16da0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
16db0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
16dc0 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
16dd0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
16de0 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e  d by this option
16df0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
16e00 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
16e10 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20  3_malloc()] for 
16e20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  the additional s
16e30 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a  torage space..**
16e40 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   The pointer in 
16e50 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
16e60 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c  nt must.** be al
16e70 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
16e80 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  te boundary or s
16e90 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
16ea0 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
16eb0 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
16ec0 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
16ed0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
16ee0 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AP]] <dt>SQLITE_
16ef0 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
16f00 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
16f10 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
16f20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
16f30 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
16f40 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
16f50 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
16f60 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
16f70 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
16f80 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
16f90 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
16fa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
16fb0 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
16fc0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
16fd0 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
16fe0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
16ff0 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  s: An 8-byte ali
17000 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
17010 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
17020 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
17030 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
17040 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
17050 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
17060 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
17070 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
17080 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
17090 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
170a0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
170b0 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
170c0 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
170d0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
170e0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
170f0 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
17100 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
17110 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
17120 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
17130 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
17140 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
17150 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
17160 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
17170 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
17180 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
17190 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
171a0 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
171b0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
171c0 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
171d0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
171e0 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
171f0 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
17200 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
17210 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
17220 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
17230 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
17240 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
17250 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
17260 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
17270 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
17280 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
17290 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
172a0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
172b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
172c0 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
172d0 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
172e0 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
172f0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
17300 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
17310 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
17320 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
17330 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
17340 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
17350 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
17360 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
17370 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
17380 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
17390 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
173a0 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
173b0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
173c0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
173d0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
173e0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
173f0 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
17400 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
17410 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
17420 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
17430 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
17440 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
17450 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
17460 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
17470 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
17480 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
17490 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
174a0 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
174b0 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
174c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
174d0 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
174e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
174f0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
17500 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
17510 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
17520 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
17530 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
17540 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
17550 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
17560 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
17570 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
17580 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
17590 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
175a0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
175b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
175c0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
175d0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
175e0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
175f0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
17600 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17610 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
17620 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17630 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
17640 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
17650 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
17660 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
17670 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
17680 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
17690 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
176a0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
176b0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
176c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
176d0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
176e0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
176f0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
17700 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
17710 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
17720 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
17730 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
17740 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
17750 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
17760 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
17770 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
17780 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
17790 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
177a0 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
177b0 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
177c0 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
177d0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
177e0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
177f0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
17800 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
17810 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
17820 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
17830 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
17840 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
17850 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
17860 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
17870 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
17880 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
17890 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
178a0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
178b0 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
178c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
178d0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
178e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
178f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
17900 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17910 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
17920 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
17930 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
17940 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
17950 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
17960 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
17970 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   the default.** 
17980 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
17990 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73  n for the lookas
179a0 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
179b0 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20  ator on each.** 
179c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
179d0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73  tion].  The firs
179e0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
179f0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
17a00 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
17a10 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
17a20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
17a30 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
17a40 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
17a50 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
17a60 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69  ection.)^  ^(Thi
17a70 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
17a80 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c  e.** <i>default<
17a90 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69  /i> lookaside si
17aa0 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  ze. The [SQLITE_
17ab0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
17ac0 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b  DE].** verb to [
17ad0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
17ae0 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
17af0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
17b00 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
17b10 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
17b20 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
17b30 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
17b40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17b50 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
17b60 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
17b70 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
17b80 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
17b90 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
17ba0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
17bb0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
17bc0 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ** an [sqlite3_p
17bd0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
17be0 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
17bf0 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
17c00 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
17c10 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
17c20 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
17c30 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74  ation.)^  ^SQLit
17c40 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
17c50 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
17c60 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
17c70 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
17c80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
17c90 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
17ca0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
17cb0 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
17cc0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
17cd0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
17ce0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
17cf0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
17d00 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
17d10 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
17d20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
17d30 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
17d40 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
17d50 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
17d60 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
17d70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
17d80 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
17d90 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
17da0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17db0 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
17dc0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
17dd0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
17de0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
17df0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
17e00 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
17e10 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
17e20 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
17e30 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
17e40 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
17e50 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
17e60 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
17e70 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
17e80 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
17e90 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
17ea0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
17eb0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
17ec0 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
17ed0 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
17ee0 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
17ef0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
17f00 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
17f10 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
17f20 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
17f30 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
17f40 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
17f50 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
17f60 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
17f70 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
17f80 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
17f90 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
17fa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17fb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
17fc0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
17fd0 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
17fe0 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
17ff0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
18000 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18010 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
18020 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
18030 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
18040 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
18050 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
18060 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
18070 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
18080 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
18090 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
180a0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
180b0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
180c0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
180d0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
180e0 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
180f0 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
18100 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
18110 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
18120 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
18130 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
18140 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
18150 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
18160 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
18170 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
18180 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
18190 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
181a0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
181b0 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
181c0 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
181d0 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
181e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
181f0 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
18200 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
18210 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
18220 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
18230 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
18240 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
18250 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74  ** <dd> This opt
18260 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
18270 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
18280 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d  ype int. If non-
18290 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52  zero, then.** UR
182a0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
182b0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
182c0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
182d0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55   is zero, then U
182e0 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69  RI handling.** i
182f0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
18300 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64  led. If URI hand
18310 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
18320 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
18330 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65  lenames.** passe
18340 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
18350 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
18360 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  open_v2()], [sql
18370 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
18380 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
18390 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
183a0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
183b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
183c0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
183d0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
183e0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
183f0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
18400 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
18410 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
18420 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
18430 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61  . If it is globa
18440 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
18450 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
18460 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
18470 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
18480 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
18490 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
184a0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
184b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
184c0 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74  ened. By default
184d0 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
184e0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
184f0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
18500 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
18510 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
18520 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
18530 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
18540 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
18550 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d..**.** [[SQLIT
18560 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
18570 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c  G_INDEX_SCAN]] <
18580 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
18590 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
185a0 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 20 54 68 69  SCAN.** <dd> Thi
185b0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
185c0 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 20   single integer 
185d0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
185e0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
185f0 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  .** a boolean in
18600 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
18610 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
18620 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
18630 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66  indices for.** f
18640 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
18650 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
18660 69 6d 69 7a 65 72 2e 20 20 54 68 65 20 64 65 66  imizer.  The def
18670 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20  ault setting is 
18680 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79  determined.** by
18690 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c   the [SQLITE_ALL
186a0 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  OW_COVERING_INDE
186b0 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d  X_SCAN] compile-
186c0 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20  time option, or 
186d0 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68  is "on".** if th
186e0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
186f0 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  option is omitte
18700 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74  d..** The abilit
18710 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  y to disable the
18720 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
18730 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
18740 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a  l table scans.**
18750 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65   is because some
18760 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64   incorrectly cod
18770 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63  ed legacy applic
18780 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c  ations might mal
18790 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 61 6c 66  function.** malf
187a0 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  unction when the
187b0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73   optimization is
187c0 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69   enabled.  Provi
187d0 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79  ding the ability
187e0 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74   to.** disable t
187f0 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
18800 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72  allows the older
18810 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74  , buggy applicat
18820 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  ion code to work
18830 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e  .** without chan
18840 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77  ge even with new
18850 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
18860 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  QLite..**.** [[S
18870 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18880 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
18890 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
188a0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
188b0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
188c0 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
188d0 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
188e0 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
188f0 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
18900 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
18910 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
18920 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
18930 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
18940 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
18950 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
18960 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  -ops..** </dl>.*
18970 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
18980 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a  NFIG_SQLLOG]].**
18990 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
189a0 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64  IG_SQLLOG.** <dd
189b0 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  >This option is 
189c0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
189d0 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70  f sqlite is comp
189e0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
189f0 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53   SQLITE_ENABLE_S
18a00 51 4c 4c 4f 47 20 70 72 65 2d 70 72 6f 63 65 73  QLLOG pre-proces
18a10 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
18a20 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
18a30 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
18a40 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
18a50 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
18a60 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
18a70 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
18a80 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
18a90 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
18aa0 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
18ab0 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
18ac0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
18ad0 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
18ae0 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
18af0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
18b00 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
18b10 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
18b20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
18b30 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
18b40 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
18b50 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
18b60 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18b70 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
18b80 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
18b90 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
18ba0 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
18bb0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
18bc0 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
18bd0 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
18be0 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
18bf0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
18c00 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
18c10 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
18c20 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
18c30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
18c40 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
18c50 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
18c60 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
18c70 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
18c80 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
18c90 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
18ca0 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
18cb0 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
18cc0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
18cd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
18ce0 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
18cf0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
18d00 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
18d10 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 0a 2a   In this case..*
18d20 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
18d30 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18d40 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
18d50 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
18d60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18d70 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
18d80 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
18d90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18da0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
18db0 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
18dc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18dd0 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
18de0 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
18df0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
18e00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18e10 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
18e20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
18e30 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
18e40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18e50 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
18e60 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
18e70 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
18e80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18e90 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
18ea0 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
18eb0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
18ec0 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
18ed0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
18ee0 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
18ef0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
18f00 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
18f10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18f20 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
18f30 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
18f40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18f50 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
18f60 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
18f70 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
18f80 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
18f90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
18fa0 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
18fb0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
18fc0 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
18fd0 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
18fe0 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
18ff0 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
19000 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
19010 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19020 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
19030 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
19040 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19050 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
19060 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
19070 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
19080 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
19090 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
190a0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
190b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
190c0 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
190d0 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
190e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
190f0 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
19100 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
19110 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19120 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
19130 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
19140 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
19150 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
19160 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
19170 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
19180 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
19190 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
191a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
191b0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
191c0 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20  DEX_SCAN 20  /* 
191d0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
191e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
191f0 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a  LOG       21  /*
19200 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20   xSqllog, void* 
19210 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
19220 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
19230 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
19240 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
19250 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
19260 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
19270 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
19280 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
19290 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
192a0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
192b0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
192c0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
192d0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
192e0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
192f0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
19300 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
19310 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
19320 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
19330 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
19340 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
19350 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
19360 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
19370 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
19380 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
19390 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
193a0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
193b0 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
193c0 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
193d0 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
193e0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
193f0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
19400 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
19410 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
19420 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
19430 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
19440 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
19450 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
19460 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
19470 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
19480 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19490 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
194a0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
194b0 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
194c0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
194d0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
194e0 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
194f0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
19500 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
19510 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
19520 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19530 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
19540 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
19550 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
19560 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
19570 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
19580 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
19590 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
195a0 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
195b0 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
195c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
195d0 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
195e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
195f0 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
19600 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
19610 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
19620 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
19630 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
19640 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
19650 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
19660 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
19670 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
19680 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
19690 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
196a0 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
196b0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
196c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
196d0 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
196e0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
196f0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
19700 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
19710 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
19720 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
19730 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
19740 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
19750 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
19760 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
19770 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
19780 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
19790 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
197a0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
197b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
197c0 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
197d0 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
197e0 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
197f0 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
19800 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
19810 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
19820 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
19830 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
19840 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
19850 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
19860 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
19870 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
19880 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
19890 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
198a0 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
198b0 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
198c0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
198d0 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
198e0 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
198f0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
19900 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
19910 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
19920 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
19930 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
19940 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
19950 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
19960 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
19970 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
19980 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
19990 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
199a0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
199b0 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
199c0 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
199d0 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
199e0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
199f0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19a00 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
19a10 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
19a20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
19a30 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
19a40 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
19a50 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
19a60 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
19a70 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
19a80 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
19a90 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
19aa0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
19ab0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
19ac0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
19ad0 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
19ae0 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
19af0 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
19b00 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
19b10 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
19b20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
19b30 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
19b40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19b50 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
19b60 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
19b70 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
19b80 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
19b90 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
19ba0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
19bb0 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
19bc0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
19bd0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
19be0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
19bf0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
19c00 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
19c10 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
19c20 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
19c30 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
19c40 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
19c50 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
19c60 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
19c70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19c80 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19c90 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
19ca0 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
19cb0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
19cc0 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
19cd0 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
19ce0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
19cf0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
19d00 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
19d10 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
19d20 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
19d30 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
19d40 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
19d50 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
19d60 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
19d70 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
19d80 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
19d90 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
19da0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
19db0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
19dc0 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
19dd0 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
19de0 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
19df0 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
19e00 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
19e10 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
19e20 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
19e30 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
19e40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
19e50 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
19e60 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
19e70 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
19e80 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
19e90 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
19ea0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19eb0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
19ec0 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
19ed0 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
19ee0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19ef0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
19f00 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
19f10 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
19f20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
19f30 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
19f40 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
19f50 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
19f60 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
19f70 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
19f80 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
19f90 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
19fa0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
19fb0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
19fc0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
19fd0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
19fe0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
19ff0 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
1a000 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
1a010 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
1a020 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
1a030 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1a040 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
1a050 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
1a060 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1a070 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
1a080 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
1a090 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
1a0a0 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
1a0b0 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
1a0c0 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
1a0d0 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61  ^Each entry in a
1a0e0 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68  n SQLite table h
1a0f0 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
1a100 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
1a110 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
1a120 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
1a130 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
1a140 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
1a150 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
1a160 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
1a170 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
1a180 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
1a190 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
1a1a0 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
1a1b0 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
1a1c0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
1a1d0 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
1a1e0 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
1a1f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
1a200 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
1a210 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
1a220 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
1a230 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
1a240 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
1a250 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1a260 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
1a270 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  ] of the most re
1a280 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
1a290 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
1a2a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
1a2b0 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
1a2c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
1a2d0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
1a2e0 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53  ument.  ^As of S
1a2f0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1a300 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  7.7, this routin
1a310 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68  es.** records th
1a320 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f  e last insert ro
1a330 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69  wid of both ordi
1a340 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20  nary tables and 
1a350 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
1a360 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
1a370 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
1a380 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
1a390 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64  curred on that d
1a3a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a3b0 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
1a3c0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  rned..**.** ^(If
1a3d0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
1a3e0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
1a3f0 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
1a400 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
1a410 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
1a420 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1a430 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
1a440 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
1a450 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
1a460 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
1a470 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
1a480 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
1a490 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
1a4a0 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
1a4b0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
1a4c0 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
1a4d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a4e0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
1a4f0 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
1a500 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
1a510 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
1a520 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
1a530 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
1a540 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
1a550 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
1a560 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
1a570 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
1a580 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
1a590 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
1a5a0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
1a5b0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
1a5c0 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
1a5d0 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
1a5e0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
1a5f0 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
1a600 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
1a610 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
1a620 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
1a630 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
1a640 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1a650 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
1a660 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
1a670 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
1a680 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
1a690 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
1a6a0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
1a6b0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
1a6c0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
1a6d0 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
1a6e0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
1a6f0 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
1a700 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
1a710 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
1a720 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
1a730 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
1a740 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
1a750 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
1a760 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1a770 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1a780 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
1a790 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
1a7a0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
1a7b0 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
1a7c0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
1a7d0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
1a7e0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
1a7f0 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
1a800 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
1a810 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
1a820 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
1a830 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
1a840 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
1a850 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
1a860 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1a870 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1a880 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
1a890 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
1a8a0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
1a8b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
1a8c0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
1a8d0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1a8e0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
1a8f0 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
1a900 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
1a910 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1a920 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
1a930 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a940 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
1a950 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1a960 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
1a970 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
1a980 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
1a990 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
1a9a0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
1a9b0 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53  rt [rowid]..*/.S
1a9c0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1a9d0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1a9e0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1a9f0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
1aa00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1aa10 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
1aa20 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
1aa30 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1aa40 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1aa50 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
1aa60 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
1aa70 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
1aa80 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
1aa90 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
1aaa0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
1aab0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1aac0 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
1aad0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1aae0 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
1aaf0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1ab00 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68  er..** ^(Only ch
1ab10 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
1ab20 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
1ab30 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
1ab40 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
1ab50 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
1ab60 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
1ab70 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
1ab80 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
1ab90 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b  ** triggers or [
1aba0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1abb0 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ons] are not cou
1abc0 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a  nted.)^ Use the.
1abd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  ** [sqlite3_tota
1abe0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
1abf0 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68  ction to find th
1ac00 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
1ac10 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63  f changes.** inc
1ac20 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
1ac30 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
1ac40 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65  s and foreign ke
1ac50 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  y actions..**.**
1ac60 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
1ac70 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
1ac80 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
1ac90 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1aca0 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
1acb0 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
1acc0 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
1acd0 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
1ace0 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67  * ^(A "row chang
1acf0 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
1ad00 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
1ad10 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
1ad20 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
1ad30 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
1ad40 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
1ad50 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
1ad60 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
1ad70 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
1ad80 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  of [REPLACE] con
1ad90 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
1ada0 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
1adb0 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
1adc0 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c  g, [DROP TABLE],
1add0 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
1ade0 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
1adf0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
1ae00 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
1ae10 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  s.)^.**.** A "tr
1ae20 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
1ae30 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
1ae40 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
1ae50 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
1ae60 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
1ae70 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
1ae80 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
1ae90 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
1aea0 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
1aeb0 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
1aec0 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
1aed0 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
1aee0 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
1aef0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
1af00 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
1af10 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
1af20 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
1af30 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
1af40 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
1af50 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
1af60 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
1af70 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
1af80 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
1af90 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
1afa0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  ation..**.** ^Ca
1afb0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
1afc0 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
1afd0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
1afe0 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
1aff0 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
1b000 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
1b010 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1b020 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1b030 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
1b040 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
1b050 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
1b060 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
1b070 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
1b080 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1b090 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
1b0a0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
1b0b0 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63  ** ^Thus, when c
1b0c0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
1b0d0 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
1b0e0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1b0f0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
1b100 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
1b110 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
1b120 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
1b130 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
1b140 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
1b150 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e  he top level.  ^
1b160 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79  (Within the body
1b170 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
1b180 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
1b190 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
1b1a0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
1b1b0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
1b1c0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
1b1d0 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
1b1e0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
1b1f0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
1b200 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
1b210 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
1b220 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
1b230 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
1b240 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
1b250 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
1b260 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
1b270 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
1b280 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
1b290 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
1b2a0 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
1b2b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
1b2c0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
1b2d0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1b2e0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
1b2f0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
1b300 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
1b310 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
1b320 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1b330 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1b340 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1b350 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1b360 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b370 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1b380 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1b390 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1b3a0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
1b3b0 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
1b3c0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1b3d0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1b3e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b3f0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1b400 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1b410 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
1b420 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
1b430 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
1b440 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
1b450 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1b460 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
1b470 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45   caused by [INSE
1b480 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  RT],.** [UPDATE]
1b490 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
1b4a0 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
1b4b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1b4c0 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e  ection] was open
1b4d0 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75  ed..** ^(The cou
1b4e0 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  nt returned by s
1b4f0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1b500 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20  nges() includes 
1b510 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66  all changes.** f
1b520 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20  rom all [CREATE 
1b530 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
1b540 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20  r] contexts and 
1b550 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a  changes made by.
1b560 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
1b570 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65  actions]. Howeve
1b580 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
1b590 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1b5a0 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
1b5b0 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c   implement [REPL
1b5c0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73  ACE] constraints
1b5d0 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
1b5e0 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
1b5f0 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20  ssing, or [DROP 
1b600 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e  TABLE] processin
1b610 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74  g.  The.** count
1b620 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1b630 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20  e rows of views 
1b640 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e  that fire an [IN
1b650 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1b660 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20  ],.** though if 
1b670 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74  the INSTEAD OF t
1b680 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61  rigger makes cha
1b690 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c  nges of its own,
1b6a0 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a   those changes .
1b6b0 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29  ** are counted.)
1b6c0 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ^.** ^The sqlite
1b6d0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1b6e0 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74  ) function count
1b6f0 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73  s the changes as
1b700 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20   soon as.** the 
1b710 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
1b720 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
1b730 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
1b740 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
1b750 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74  e.** is passed t
1b760 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
1b770 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1b780 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
1b790 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
1b7a0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1b7b0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1b7c0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1b7d0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1b7e0 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
1b7f0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1b800 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1b810 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1b820 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1b830 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1b840 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1b850 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1b860 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1b870 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1b880 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
1b890 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
1b8a0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1b8b0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1b8c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b8d0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1b8e0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1b8f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b900 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
1b910 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
1b920 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1b930 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
1b940 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
1b950 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
1b960 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
1b970 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
1b980 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
1b990 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
1b9a0 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
1b9b0 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
1b9c0 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
1b9d0 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
1b9e0 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
1b9f0 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
1ba00 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
1ba10 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
1ba20 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
1ba30 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
1ba40 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
1ba50 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1ba60 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
1ba70 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
1ba80 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
1ba90 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
1baa0 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
1bab0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
1bac0 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
1bad0 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
1bae0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1baf0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1bb00 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
1bb10 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
1bb20 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
1bb30 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1bb40 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
1bb50 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
1bb60 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
1bb70 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
1bb80 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
1bb90 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
1bba0 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
1bbb0 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
1bbc0 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
1bbd0 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
1bbe0 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
1bbf0 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
1bc00 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
1bc10 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
1bc20 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
1bc30 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
1bc40 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
1bc50 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
1bc60 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
1bc70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
1bc80 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
1bc90 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
1bca0 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
1bcb0 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
1bcc0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
1bcd0 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
1bce0 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
1bcf0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
1bd00 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
1bd10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1bd20 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
1bd30 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
1bd40 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
1bd50 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
1bd60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
1bd70 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
1bd80 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
1bd90 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
1bda0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1bdb0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1bdc0 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
1bdd0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1bde0 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
1bdf0 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
1be00 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
1be10 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
1be20 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
1be30 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
1be40 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
1be50 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1be60 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
1be70 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
1be80 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1be90 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1bea0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
1beb0 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
1bec0 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
1bed0 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
1bee0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1bef0 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
1bf00 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
1bf10 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
1bf20 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
1bf30 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
1bf40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1bf50 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
1bf60 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
1bf70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1bf80 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1bf90 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1bfa0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1bfb0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
1bfc0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
1bfd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1bfe0 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
1bff0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1c000 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
1c010 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
1c020 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
1c030 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
1c040 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1c050 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
1c060 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1c070 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
1c080 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
1c090 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
1c0a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1c0b0 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
1c0c0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
1c0d0 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
1c0e0 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
1c0f0 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
1c100 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
1c110 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
1c120 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
1c130 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
1c140 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
1c150 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
1c160 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
1c170 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
1c180 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
1c190 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
1c1a0 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
1c1b0 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
1c1c0 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
1c1d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
1c1e0 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
1c1f0 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
1c200 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
1c210 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
1c220 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
1c230 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
1c240 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
1c250 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
1c260 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
1c270 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
1c280 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
1c290 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
1c2a0 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
1c2b0 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
1c2c0 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
1c2d0 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
1c2e0 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
1c2f0 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
1c300 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
1c310 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
1c320 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
1c330 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
1c340 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
1c350 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
1c360 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
1c370 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
1c380 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
1c390 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
1c3a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
1c3b0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
1c3c0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
1c3d0 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
1c3e0 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
1c3f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
1c400 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
1c410 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
1c420 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1c430 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
1c440 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
1c450 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
1c460 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
1c470 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
1c480 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
1c490 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
1c4a0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
1c4b0 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
1c4c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
1c4d0 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
1c4e0 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
1c4f0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1c500 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
1c510 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
1c520 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
1c530 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
1c540 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
1c550 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
1c560 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
1c570 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
1c580 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
1c590 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1c5a0 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
1c5b0 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
1c5c0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
1c5d0 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
1c5e0 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
1c5f0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
1c600 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
1c610 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
1c620 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1c630 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
1c640 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
1c650 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1c660 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
1c670 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
1c680 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
1c690 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
1c6a0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
1c6b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1c6c0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1c6d0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
1c6e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
1c6f0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
1c700 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
1c710 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
1c720 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
1c730 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
1c740 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
1c750 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e  Y Errors.**.** ^
1c760 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1c770 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1c780 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
1c790 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
1c7a0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
1c7b0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
1c7c0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
1c7d0 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
1c7e0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
1c7f0 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
1c800 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1c810 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1c820 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
1c830 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
1c840 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
1c850 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
1c860 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
1c870 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
1c880 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
1c890 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1c8a0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
1c8b0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
1c8c0 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
1c8d0 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
1c8e0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
1c8f0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1c900 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
1c910 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
1c920 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
1c930 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
1c940 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
1c950 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1c960 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
1c970 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
1c980 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
1c990 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
1c9a0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
1c9b0 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
1c9c0 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
1c9d0 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
1c9e0 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
1c9f0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
1ca00 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
1ca10 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1ca20 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
1ca30 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
1ca40 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
1ca50 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1ca60 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
1ca70 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
1ca80 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
1ca90 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
1caa0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
1cab0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1cac0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
1cad0 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
1cae0 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
1caf0 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
1cb00 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
1cb10 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
1cb20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
1cb30 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
1cb40 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
1cb50 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
1cb60 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
1cb70 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
1cb80 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
1cb90 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
1cba0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
1cbb0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
1cbc0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
1cbd0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
1cbe0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
1cbf0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
1cc00 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
1cc10 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
1cc20 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
1cc30 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
1cc40 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
1cc50 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
1cc60 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
1cc70 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1cc80 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
1cc90 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
1cca0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
1ccb0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1ccc0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
1ccd0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1cce0 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
1ccf0 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
1cd00 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
1cd10 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
1cd20 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
1cd30 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
1cd40 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
1cd50 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1cd60 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
1cd70 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
1cd80 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
1cd90 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
1cda0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1cdb0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
1cdc0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
1cdd0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
1cde0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
1cdf0 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
1ce00 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
1ce10 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
1ce20 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
1ce30 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
1ce40 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1ce50 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
1ce60 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
1ce70 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
1ce80 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
1ce90 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
1cea0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
1ceb0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
1cec0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
1ced0 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
1cee0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1cef0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  L..**.** ^The [S
1cf00 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
1cf10 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
1cf20 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
1cf30 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
1cf40 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
1cf50 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
1cf60 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
1cf70 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
1cf80 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
1cf90 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
1cfa0 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
1cfb0 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
1cfc0 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
1cfd0 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
1cfe0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1cff0 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
1d000 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
1d010 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
1d020 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
1d030 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
1d040 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
1d050 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1d060 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
1d070 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
1d080 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69  aders.  ^If it i
1d090 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
1d0a0 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
1d0b0 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
1d0c0 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
1d0d0 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
1d0e0 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
1d0f0 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
1d100 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
1d110 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
1d120 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
1d130 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
1d140 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
1d150 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
1d160 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68  R_BLOCKED].  ^Th
1d170 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
1d180 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
1d190 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
1d1a0 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
1d1b0 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
1d1c0 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
1d1d0 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
1d1e0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
1d1f0 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
1d200 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
1d210 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
1d220 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
1d230 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
1d240 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
1d250 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ortant..**.** ^(
1d260 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1d270 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1d280 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
1d290 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
1d2a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d2b0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
1d2c0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
1d2d0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
1d2e0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
1d2f0 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
1d300 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
1d310 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1d320 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
1d330 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
1d340 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1d350 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
1d360 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
1d370 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
1d380 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
1d390 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1d3a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1d3b0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1d3c0 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20  y handler.  Any 
1d3d0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1d3e0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1d3f0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1d400 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1d410 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1d420 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1d430 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1d440 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1d450 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1d460 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1d470 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ler..*/.SQLITE_A
1d480 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
1d490 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1d4a0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
1d4b0 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
1d4c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d4d0 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1d4e0 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
1d4f0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1d500 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1d510 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1d520 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1d530 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1d540 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1d550 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1d560 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1d570 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1d580 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1d590 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1d5a0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1d5b0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1d5c0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1d5d0 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1d5e0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1d5f0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1d600 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1d610 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1d620 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1d630 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d640 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1d650 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
1d660 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
1d670 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
1d680 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
1d690 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
1d6a0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
1d6b0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
1d6c0 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
1d6d0 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
1d6e0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1d6f0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1d700 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
1d710 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
1d720 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1d730 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
1d740 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
1d750 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
1d760 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
1d770 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
1d780 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1d790 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
1d7a0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
1d7b0 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
1d7c0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1d7d0 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
1d7e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1d7f0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
1d800 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1d810 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1d820 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1d830 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1d840 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1d850 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ies.**.** This i
1d860 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1d870 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1d880 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1d890 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1d8a0 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1d8b0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1d8c0 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1d8d0 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1d8e0 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1d8f0 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1d900 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1d910 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1d920 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1d930 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1d940 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1d950 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1d960 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1d970 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1d980 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1d990 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1d9a0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1d9b0 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1d9c0 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1d9d0 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1d9e0 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1d9f0 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1da00 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1da10 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1da20 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1da30 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1da40 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1da50 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1da60 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1da70 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1da80 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1da90 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1daa0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1dab0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1dac0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1dad0 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1dae0 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1daf0 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1db00 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1db10 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1db20 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1db30 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1db40 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1db50 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1db60 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1db70 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1db80 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1db90 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1dba0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1dbb0 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1dbc0 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1dbd0 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1dbe0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1dbf0 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1dc00 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1dc10 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1dc20 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1dc30 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1dc40 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1dc50 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1dc60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1dc70 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1dc80 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1dc90 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1dca0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1dcb0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1dcc0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1dcd0 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1dce0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1dcf0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1dd00 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1dd10 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1dd20 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1dd30 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1dd40 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1dd50 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1dd60 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1dd70 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1dd80 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1dd90 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1dda0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1ddb0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1ddc0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1ddd0 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1dde0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1ddf0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1de00 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1de10 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1de20 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1de30 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1de40 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1de50 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1de60 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1de70 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1de80 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1de90 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1dea0 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1deb0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1dec0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1ded0 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1dee0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1def0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1df00 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1df10 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1df20 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1df30 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1df40 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1df50 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1df60 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1df70 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1df80 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1df90 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1dfa0 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1dfb0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1dfc0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1dfd0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1dfe0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1dff0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1e000 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1e010 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1e020 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1e030 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e040 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1e050 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1e060 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1e070 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1e080 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1e090 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1e0a0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1e0b0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1e0c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1e0d0 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1e0e0 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1e0f0 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1e100 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1e110 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1e120 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1e130 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1e140 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1e150 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1e160 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1e170 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1e180 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1e190 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1e1a0 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1e1b0 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1e1c0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1e1d0 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1e1e0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1e1f0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1e200 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1e210 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1e220 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1e230 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1e240 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1e250 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1e260 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1e270 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1e280 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1e290 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1e2a0 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1e2b0 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1e2c0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1e2d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1e2e0 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1e2f0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1e300 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1e310 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1e320 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1e330 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1e340 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1e350 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1e360 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1e370 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1e380 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1e390 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1e3a0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1e3b0 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1e3c0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1e3d0 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1e3e0 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1e3f0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1e400 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1e410 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1e420 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1e430 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1e440 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1e450 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1e460 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1e470 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1e480 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  rrmsg()]..*/.SQL
1e490 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1e4a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1e4b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1e4c0 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1e4d0 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1e4e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1e4f0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1e500 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1e510 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1e520 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1e530 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1e540 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1e550 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1e560 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1e570 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1e580 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1e590 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1e5a0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1e5b0 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1e5c0 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1e5d0 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1e5e0 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1e5f0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1e600 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1e610 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1e620 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1e630 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e640 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1e650 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1e660 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1e670 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1e680 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1e690 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1e6a0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1e6b0 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1e6c0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1e6d0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1e6e0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1e6f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
1e700 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
1e710 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
1e720 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
1e730 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
1e740 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1e750 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
1e760 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1e770 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
1e780 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
1e790 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
1e7a0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
1e7b0 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
1e7c0 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
1e7d0 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
1e7e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
1e7f0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1e800 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
1e810 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1e820 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
1e830 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1e840 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1e850 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
1e860 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
1e870 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
1e880 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1e890 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
1e8a0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
1e8b0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
1e8c0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
1e8d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
1e8e0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
1e8f0 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
1e900 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
1e910 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
1e920 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
1e930 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
1e940 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
1e950 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
1e960 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
1e970 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
1e980 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
1e990 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
1e9a0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
1e9b0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1e9c0 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
1e9d0 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
1e9e0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
1e9f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1ea00 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
1ea10 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
1ea20 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
1ea30 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
1ea40 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
1ea50 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
1ea60 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
1ea70 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1ea80 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
1ea90 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
1eaa0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
1eab0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
1eac0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
1ead0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
1eae0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1eaf0 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
1eb00 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
1eb10 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
1eb20 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
1eb30 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
1eb40 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
1eb50 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1eb60 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
1eb70 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
1eb80 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
1eb90 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
1eba0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1ebb0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
1ebc0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
1ebd0 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
1ebe0 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
1ebf0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
1ec00 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
1ec10 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
1ec20 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
1ec30 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
1ec40 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
1ec50 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
1ec60 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
1ec70 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1ec80 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
1ec90 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1eca0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
1ecb0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
1ecc0 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
1ecd0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
1ece0 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
1ecf0 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
1ed00 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
1ed10 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
1ed20 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
1ed30 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
1ed40 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1ed50 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
1ed60 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
1ed70 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
1ed80 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
1ed90 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1eda0 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1edb0 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1edc0 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1edd0 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
1ede0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
1edf0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
1ee00 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
1ee10 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
1ee20 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
1ee30 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
1ee40 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
1ee50 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1ee60 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
1ee70 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
1ee80 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
1ee90 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
1eea0 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
1eeb0 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
1eec0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
1eed0 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
1eee0 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
1eef0 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
1ef00 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
1ef10 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
1ef20 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1ef30 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1ef40 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
1ef50 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
1ef60 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1ef70 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
1ef80 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
1ef90 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
1efa0 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
1efb0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1efc0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1efd0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1efe0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1eff0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1f000 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
1f010 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1f020 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1f030 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1f040 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1f050 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1f060 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1f070 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
1f080 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
1f090 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
1f0a0 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
1f0b0 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
1f0c0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
1f0d0 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
1f0e0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1f0f0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1f100 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1f110 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
1f120 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1f130 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1f140 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1f150 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1f160 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1f170 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1f180 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1f190 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1f1a0 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1f1b0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1f1c0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1f1d0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1f1e0 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1f1f0 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1f200 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1f210 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1f220 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1f230 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1f240 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1f250 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1f260 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1f270 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1f280 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1f290 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1f2a0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1f2b0 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1f2c0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1f2d0 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1f2e0 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1f2f0 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1f300 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1f310 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1f320 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1f330 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1f340 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1f350 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1f360 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1f370 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1f380 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1f390 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1f3a0 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1f3b0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1f3c0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1f3d0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1f3e0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1f3f0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1f400 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1f410 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1f420 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1f430 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1f440 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1f450 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1f460 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1f470 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1f480 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1f490 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1f4a0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1f4b0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1f4c0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1f4d0 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1f4e0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1f4f0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1f500 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
1f510 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
1f520 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
1f530 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
1f540 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
1f550 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
1f560 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
1f570 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
1f580 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
1f590 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
1f5a0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
1f5b0 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53  t string.)^.*/.S
1f5c0 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1f5d0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1f5e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
1f5f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1f600 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1f610 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1f620 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54   va_list);.SQLIT
1f630 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1f640 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1f650 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1f660 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  r*, ...);.SQLITE
1f670 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1f680 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1f690 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1f6a0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1f6b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1f6c0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1f6d0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1f6e0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1f6f0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1f700 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1f710 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1f720 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1f730 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1f740 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1f750 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1f760 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1f770 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1f780 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1f790 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1f7a0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1f7b0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1f7c0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1f7d0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1f7e0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1f7f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f800 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1f810 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1f820 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1f830 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1f840 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1f850 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1f860 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1f870 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1f880 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1f890 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1f8a0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1f8b0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1f8c0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1f8d0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1f8e0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1f8f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1f900 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1f910 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1f920 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1f930 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1f940 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
1f950 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1f960 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1f970 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1f980 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1f990 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1f9a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f9b0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1f9c0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1f9d0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1f9e0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1f9f0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1fa00 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1fa10 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1fa20 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1fa30 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1fa40 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1fa50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1fa60 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1fa70 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1fa80 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1fa90 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1faa0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1fab0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1fac0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1fad0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1fae0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1faf0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1fb00 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1fb10 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1fb20 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1fb30 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1fb40 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1fb50 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1fb60 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1fb70 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1fb80 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1fb90 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1fba0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1fbb0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1fbc0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1fbd0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1fbe0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1fbf0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
1fc00 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1fc10 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1fc20 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1fc30 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
1fc40 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
1fc50 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
1fc60 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1fc70 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
1fc80 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1fc90 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
1fca0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1fcb0 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
1fcc0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1fcd0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fce0 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
1fcf0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1fd00 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1fd10 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1fd20 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1fd30 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
1fd40 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1fd50 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1fd60 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1fd70 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
1fd80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1fd90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
1fda0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1fdb0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1fdc0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1fdd0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1fde0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1fdf0 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
1fe00 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
1fe10 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1fe20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1fe30 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1fe40 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
1fe50 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1fe60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1fe70 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1fe80 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1fe90 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
1fea0 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
1feb0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1fec0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1fed0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1fee0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1fef0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1ff00 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1ff10 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1ff20 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1ff30 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1ff40 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1ff50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
1ff60 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1ff70 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1ff80 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1ff90 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1ffa0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
1ffb0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1ffc0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
1ffd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
1ffe0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1fff0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
20000 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
20010 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
20020 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
20030 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
20040 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
20050 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
20060 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
20070 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
20080 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
20090 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
200a0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
200b0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
200c0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
200d0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
200e0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
200f0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
20100 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
20110 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
20120 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
20130 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
20140 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
20150 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
20160 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
20170 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
20180 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
20190 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
201a0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
201b0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
201c0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
201d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
201e0 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
201f0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
20200 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
20210 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
20220 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
20230 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
20240 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
20250 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
20260 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
20270 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
20280 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
20290 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
202a0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
202b0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
202c0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
202d0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
202e0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
202f0 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
20300 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
20310 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
20320 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
20330 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
20340 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
20350 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
20360 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
20370 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
20380 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
20390 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
203a0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
203b0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
203c0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
203d0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
203e0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
203f0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
20400 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
20410 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
20420 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
20430 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
20440 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
20450 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
20460 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
20470 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
20480 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
20490 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
204a0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
204b0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
204c0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
204d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
204e0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
204f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d   void *sqlite3_m
20500 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49  alloc(int);.SQLI
20510 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
20520 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
20530 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
20540 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
20550 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
20560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20570 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
20580 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
20590 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
205a0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
205b0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
205c0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
205d0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
205e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
205f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
20600 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
20610 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
20620 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
20630 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
20640 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
20650 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
20660 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
20670 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
20680 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
20690 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
206a0 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
206b0 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
206c0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
206d0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
206e0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
206f0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
20700 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
20710 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
20720 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
20730 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20740 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
20750 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
20760 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
20770 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
20780 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
20790 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
207a0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
207b0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
207c0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
207d0 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
207e0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
207f0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
20800 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
20810 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
20820 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
20830 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
20840 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
20850 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
20860 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
20870 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
20880 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
20890 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
208a0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
208b0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
208c0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
208d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
208e0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
208f0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
20900 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
20910 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
20920 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
20930 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
20940 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
20950 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20960 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
20970 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
20980 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
20990 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54   reset..*/.SQLIT
209a0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
209b0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
209c0 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53  ry_used(void);.S
209d0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
209e0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
209f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
20a00 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
20a10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20a20 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
20a30 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
20a40 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
20a50 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
20a60 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
20a70 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
20a80 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
20a90 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
20aa0 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
20ab0 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
20ac0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
20ad0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
20ae0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
20af0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
20b00 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
20b10 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
20b20 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
20b30 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
20b40 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
20b50 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
20b60 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
20b70 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
20b80 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
20b90 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
20ba0 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
20bb0 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
20bc0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
20bd0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
20be0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
20bf0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
20c00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
20c10 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
20c20 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
20c30 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
20c40 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
20c50 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
20c60 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
20c70 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
20c80 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
20c90 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
20ca0 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
20cb0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
20cc0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
20cd0 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
20ce0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
20cf0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
20d00 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
20d10 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
20d20 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
20d30 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
20d40 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
20d50 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
20d60 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
20d70 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61   void sqlite3_ra
20d80 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
20d90 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
20da0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
20db0 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
20dc0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
20dd0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
20de0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
20df0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20e00 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
20e10 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
20e20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
20e30 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
20e40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
20e50 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
20e60 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20e70 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
20e80 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
20e90 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
20ea0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
20eb0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
20ec0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
20ed0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
20ee0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
20ef0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
20f00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20f10 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
20f20 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
20f30 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
20f40 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
20f50 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
20f60 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
20f70 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
20f80 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
20f90 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
20fa0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
20fb0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
20fc0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
20fd0 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
20fe0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
20ff0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
21000 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
21010 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
21020 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
21030 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
21040 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
21050 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
21060 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
21070 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
21080 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
21090 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
210a0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
210b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
210c0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
210d0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
210e0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
210f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
21100 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
21110 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
21120 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
21130 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
21140 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
21150 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
21160 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
21170 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
21180 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
21190 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
211a0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
211b0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
211c0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
211d0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
211e0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
211f0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
21200 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
21210 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
21220 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
21230 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
21240 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
21250 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21260 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
21270 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
21280 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
21290 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
212a0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
212b0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
212c0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
212d0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
212e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
212f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
21300 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21310 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
21320 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
21330 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21340 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
21350 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
21360 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
21370 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
21380 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
21390 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
213a0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
213b0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
213c0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
213d0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
213e0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
213f0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
21400 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
21410 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
21420 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
21430 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
21440 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
21450 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
21460 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
21470 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
21480 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
21490 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
214a0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
214b0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
214c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
214d0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
214e0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
214f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21500 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
21510 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
21520 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
21530 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
21540 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
21550 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
21560 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
21570 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
21580 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
21590 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
215a0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
215b0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
215c0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
215d0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
215e0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
215f0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
21600 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
21610 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
21620 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
21630 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
21640 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
21650 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
21660 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
21670 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
21680 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
21690 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
216a0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
216b0 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
216c0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
216d0 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
216e0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
216f0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
21700 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
21710 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
21720 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
21730 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
21740 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
21750 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
21760 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
21770 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
21780 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
21790 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
217a0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
217b0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
217c0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
217d0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
217e0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
217f0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
21800 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
21810 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
21820 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
21830 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
21840 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
21850 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
21860 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
21870 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
21880 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
21890 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
218a0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
218b0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
218c0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
218d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
218e0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
218f0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
21900 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
21910 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
21920 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
21930 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
21940 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
21950 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
21960 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
21970 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
21980 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
21990 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
219a0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
219b0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
219c0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
219d0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
219e0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
219f0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
21a00 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
21a10 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
21a20 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
21a30 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
21a40 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
21a50 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
21a60 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
21a70 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
21a80 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
21a90 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
21aa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21ab0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
21ac0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
21ad0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
21ae0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
21af0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
21b00 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
21b10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21b20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
21b30 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
21b40 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
21b50 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
21b60 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
21b70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21b80 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
21b90 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
21ba0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
21bb0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
21bc0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
21bd0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
21be0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
21bf0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
21c00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21c10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
21c20 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
21c30 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
21c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
21c50 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
21c60 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
21c70 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
21c80 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
21c90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21ca0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
21cb0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
21cc0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
21cd0 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
21ce0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
21cf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21d00 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
21d10 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
21d20 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
21d30 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
21d40 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
21d50 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
21d60 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
21d70 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
21d80 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
21d90 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
21da0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
21db0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21dc0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
21dd0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
21de0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
21df0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
21e00 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
21e10 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
21e20 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
21e30 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
21e40 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
21e50 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
21e60 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
21e70 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
21e80 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
21e90 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
21ea0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21eb0 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
21ec0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
21ed0 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
21ee0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
21ef0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74   int sqlite3_set
21f00 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
21f10 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
21f20 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
21f30 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
21f40 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
21f50 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
21f60 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
21f70 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
21f80 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
21f90 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
21fa0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
21fb0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21fc0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
21fd0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
21fe0 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
21ff0 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
22000 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
22010 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
22020 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
22030 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
22040 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
22050 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
22060 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
22070 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
22080 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
22090 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
220a0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
220b0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
220c0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
220d0 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
220e0 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
220f0 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
22100 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
22110 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
22120 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
22130 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
22140 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
22150 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
22160 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
22170 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
22180 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
22190 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
221a0 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
221b0 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
221c0 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
221d0 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
221e0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
221f0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
22200 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
22210 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
22220 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
22230 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
22240 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
22250 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
22260 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
22270 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
22280 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
22290 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
222a0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
222b0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
222c0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
222d0 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
222e0 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
222f0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
22300 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
22310 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
22320 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
22330 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
22340 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
22350 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
22360 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
22370 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
22380 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
22390 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
223a0 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
223b0 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
223c0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
223d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
223e0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
223f0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
22400 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
22410 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
22420 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
22430 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
22440 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
22450 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
22460 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
22470 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
22480 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
22490 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
224a0 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
224b0 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
224c0 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
224d0 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
224e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
224f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22500 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
22510 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
22520 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
22530 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
22540 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
22550 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
22560 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
22570 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
22580 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
22590 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
225a0 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
225b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
225c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
225d0 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
225e0 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
225f0 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
22600 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22610 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
22620 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
22630 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
22640 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22650 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22660 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
22670 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22680 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22690 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
226a0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
226b0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
226c0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
226d0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
226e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
226f0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
22700 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
22710 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22720 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22730 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22740 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
22750 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
22760 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
22770 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22780 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22790 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
227a0 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
227b0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
227c0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
227d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
227e0 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
227f0 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
22800 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
22810 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22820 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22830 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
22840 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
22850 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
22860 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22870 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22880 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
22890 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
228a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
228b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
228c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
228d0 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
228e0 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
228f0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
22900 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22910 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22920 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
22930 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
22940 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22950 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22960 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22970 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
22980 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
22990 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
229a0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
229b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
229c0 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
229d0 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
229e0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
229f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22a00 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22a10 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
22a20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
22a30 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
22a40 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22a50 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22a60 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
22a70 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
22a80 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
22a90 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22aa0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22ab0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
22ac0 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
22ad0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
22ae0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22af0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
22b00 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
22b10 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
22b20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22b30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22b40 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
22b50 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
22b60 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22b70 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22b80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22b90 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
22ba0 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
22bb0 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
22bc0 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
22bd0 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
22be0 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
22bf0 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
22c00 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22c10 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
22c20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22c30 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
22c40 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
22c50 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
22c60 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22c70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22c80 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
22c90 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
22ca0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
22cb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22cc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22cd0 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
22ce0 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
22cf0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22d00 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
22d10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22d20 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
22d30 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
22d40 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
22d50 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22d60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22d70 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
22d80 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
22d90 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
22da0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22db0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22dc0 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
22dd0 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
22de0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
22df0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22e00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
22e10 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
22e20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
22e30 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
22e40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22e50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
22e60 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
22e70 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
22e80 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22e90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22ea0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22eb0 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
22ec0 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
22ed0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
22ee0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
22ef0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22f00 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
22f10 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
22f20 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
22f30 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
22f40 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
22f50 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
22f60 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
22f70 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
22f80 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
22f90 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
22fa0 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
22fb0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
22fc0 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
22fd0 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
22fe0 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
22ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
23000 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
23010 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
23020 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
23030 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
23040 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
23050 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
23060 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
23070 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
23080 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
23090 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
230a0 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
230b0 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
230c0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
230d0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
230e0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
230f0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
23100 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
23110 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
23120 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
23130 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
23140 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
23150 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
23160 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
23170 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
23180 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
23190 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
231a0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
231b0 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
231c0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
231d0 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
231e0 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
231f0 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
23200 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
23210 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
23220 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
23230 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
23240 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
23250 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
23260 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
23270 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
23280 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
23290 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
232a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
232b0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
232c0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
232d0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
232e0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
232f0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
23300 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
23310 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
23320 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
23330 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
23340 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
23350 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
23360 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
23370 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
23380 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
23390 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
233a0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
233b0 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
233c0 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
233d0 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
233e0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
233f0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
23400 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
23410 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
23420 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
23430 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
23440 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
23450 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
23460 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
23470 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23480 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
23490 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
234a0 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
234b0 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
234c0 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
234d0 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
234e0 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
234f0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
23500 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
23510 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
23520 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
23530 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
23540 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
23550 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
23560 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
23570 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
23580 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
23590 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
235a0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
235b0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
235c0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
235d0 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
235e0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
235f0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
23600 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
23610 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
23620 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
23630 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
23640 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
23650 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
23660 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
23670 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
23680 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
23690 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
236a0 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
236b0 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
236c0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
236d0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
236e0 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
236f0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
23700 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
23710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23720 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
23730 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
23740 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
23750 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
23760 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
23770 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
23780 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
23790 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
237a0 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
237b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
237c0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
237d0 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
237e0 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
237f0 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
23800 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
23810 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
23820 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
23830 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
23840 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
23850 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
23860 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  ck X..**.** ^Onl
23870 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
23880 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
23890 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
238a0 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
238b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
238c0 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
238d0 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
238e0 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
238f0 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
23900 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
23910 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
23920 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
23930 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
23940 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
23950 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
23960 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
23970 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
23980 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
23990 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
239a0 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
239b0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
239c0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
239d0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
239e0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
239f0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
23a00 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
23a10 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
23a20 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
23a30 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
23a40 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
23a50 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
23a60 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
23a70 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
23a80 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
23a90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
23aa0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
23ab0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
23ac0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
23ad0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
23ae0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
23af0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
23b00 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
23b10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23b20 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
23b30 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
23b40 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
23b50 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ..**.*/.SQLITE_A
23b60 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
23b70 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
23b80 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
23b90 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
23ba0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
23bb0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
23bc0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
23bd0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
23be0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
23bf0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
23c00 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
23c10 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
23c20 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
23c30 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
23c40 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
23c50 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
23c60 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
23c70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
23c80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23c90 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
23ca0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
23cb0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
23cc0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
23cd0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
23ce0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
23cf0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
23d00 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
23d10 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
23d20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
23d30 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
23d40 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
23d50 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
23d60 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
23d70 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
23d80 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
23d90 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
23da0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
23db0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
23dc0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
23dd0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
23de0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
23df0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
23e00 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
23e10 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
23e20 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
23e30 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
23e40 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
23e50 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
23e60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
23e70 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
23e80 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
23e90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
23ea0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
23eb0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
23ec0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
23ed0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
23ee0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
23ef0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
23f00 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
23f10 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
23f20 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
23f30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
23f40 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
23f50 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
23f60 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
23f70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23f80 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
23f90 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
23fa0 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
23fb0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
23fc0 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
23fd0 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
23fe0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
23ff0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
24000 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
24010 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
24020 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
24030 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
24040 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24050 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
24060 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
24070 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
24080 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
24090 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
240a0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
240b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
240c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
240d0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
240e0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
240f0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
24100 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
24110 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
24120 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
24130 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
24140 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
24150 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
24160 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
24170 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
24180 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24190 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
241a0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
241b0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
241c0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
241d0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
241e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
241f0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
24200 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
24210 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
24220 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
24230 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
24240 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
24250 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
24260 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
24270 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
24280 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
24290 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
242a0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
242b0 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
242c0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
242d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
242e0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
242f0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
24300 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
24310 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
24320 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
24330 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
24340 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
24350 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
24360 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
24370 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
24380 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
24390 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
243a0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
243b0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
243c0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
243d0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
243e0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
243f0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
24400 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
24410 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
24420 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
24430 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
24440 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
24450 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
24460 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
24470 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24480 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
24490 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
244a0 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
244b0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
244c0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
244d0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
244e0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
244f0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
24500 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
24510 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
24520 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
24530 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
24540 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
24550 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
24560 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
24570 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
24580 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
24590 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
245a0 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
245b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
245c0 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
245d0 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
245e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
245f0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
24600 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
24610 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
24620 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
24630 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
24640 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24650 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
24660 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
24670 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
24680 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
24690 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
246a0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
246b0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
246c0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
246d0 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
246e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
246f0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
24700 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
24710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24720 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
24730 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
24740 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
24750 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
24760 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
24770 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
24780 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
24790 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
247a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
247b0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
247c0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
247d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
247e0 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
247f0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
24800 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
24810 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
24820 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
24830 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
24840 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
24850 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
24860 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
24870 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
24880 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
24890 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
248a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
248b0 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
248c0 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
248d0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
248e0 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
248f0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
24900 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
24910 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
24920 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
24930 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
24940 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
24950 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
24960 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
24970 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
24980 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
24990 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
249a0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
249b0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
249c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
249d0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
249e0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
249f0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
24a00 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
24a10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
24a20 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
24a30 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
24a40 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
24a50 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
24a60 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
24a70 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
24a80 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
24a90 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
24aa0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
24ab0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
24ac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
24ad0 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
24ae0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
24af0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
24b00 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
24b10 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
24b20 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
24b30 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
24b40 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
24b50 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
24b60 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
24b70 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
24b80 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
24b90 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
24ba0 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
24bb0 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
24bc0 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
24bd0 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
24be0 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
24bf0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
24c00 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
24c10 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
24c20 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
24c30 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
24c40 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
24c50 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
24c60 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
24c70 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
24c80 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
24c90 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
24ca0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
24cb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
24cc0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
24cd0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
24ce0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
24cf0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
24d00 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
24d10 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
24d20 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
24d30 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
24d40 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
24d50 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
24d60 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
24d70 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
24d80 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
24d90 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
24da0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
24db0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
24dc0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
24dd0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
24de0 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
24df0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
24e00 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
24e10 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
24e20 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
24e30 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
24e40 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
24e50 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
24e60 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
24e70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
24e80 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
24e90 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
24ea0 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
24eb0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
24ec0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
24ed0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
24ee0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
24ef0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
24f00 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
24f10 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
24f20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
24f30 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
24f40 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
24f50 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
24f60 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
24f70 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
24f80 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
24f90 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
24fa0 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
24fb0 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
24fc0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
24fd0 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
24fe0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
24ff0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
25000 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
25010 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
25020 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
25030 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
25040 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
25050 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
25060 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
25070 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
25080 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
25090 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
250a0 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
250b0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
250c0 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
250d0 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
250e0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
250f0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
25100 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
25110 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
25120 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
25130 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
25140 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
25150 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
25160 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
25170 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
25180 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
25190 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
251a0 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
251b0 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
251c0 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
251d0 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
251e0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
251f0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
25200 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
25210 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
25220 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
25230 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
25240 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69  path. .** ^On wi
25250 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
25260 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
25270 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
25280 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
25290 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
252a0 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b  . "C:")..**.** [
252b0 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
252c0 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
252d0 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
252e0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
252f0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
25300 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
25310 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
25320 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
25330 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
25340 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
25350 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
25360 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  ** SQLite interp
25370 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69  rets the followi
25380 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70  ng three query p
25390 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
253a0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
253b0 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
253c0 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
253d0 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
253e0 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
253f0 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
25400 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
25410 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
25420 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
25430 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
25440 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
25450 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
25460 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
25470 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
25480 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
25490 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
254a0 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
254b0 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
254c0 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
254d0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
254e0 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
254f0 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
25500 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
25510 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
25520 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
25530 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
25540 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
25550 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
25560 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
25570 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
25580 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
25590 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
255a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
255b0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
255c0 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
255d0 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
255e0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
255f0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
25600 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
25610 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
25620 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
25630 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
25640 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
25650 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
25660 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
25670 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
25680 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
25690 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
256a0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
256b0 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
256c0 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
256d0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
256e0 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
256f0 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
25700 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
25710 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
25720 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
25730 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
25740 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
25750 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
25760 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
25770 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
25780 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
25790 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
257a0 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
257b0 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
257c0 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
257d0 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
257e0 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
257f0 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
25800 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
25810 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
25820 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
25830 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
25840 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
25850 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
25860 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
25870 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
25880 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
25890 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
258a0 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
258b0 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
258c0 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
258d0 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
258e0 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
258f0 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
25900 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
25910 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
25920 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
25930 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
25940 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
25950 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
25960 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
25970 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
25980 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
25990 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
259a0 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
259b0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
259c0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
259d0 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
259e0 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
259f0 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
25a00 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
25a10 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
25a20 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
25a30 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
25a40 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
25a50 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
25a60 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
25a70 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
25a80 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
25a90 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
25aa0 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
25ab0 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
25ac0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
25ad0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
25ae0 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
25af0 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
25b00 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
25b10 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
25b20 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
25b30 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
25b40 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
25b50 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
25b60 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
25b70 75 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  ur requested by 
25b80 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
25b90 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
25ba0 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
25bb0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
25bc0 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c  HE flag..** </ul
25bd0 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
25be0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
25bf0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
25c00 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
25c10 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
25c20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
25c30 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
25c40 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
25c50 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
25c60 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
25c70 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
25c80 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
25c90 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
25ca0 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
25cb0 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
25cc0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
25cd0 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
25ce0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
25cf0 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
25d00 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
25d10 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
25d20 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
25d30 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
25d40 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
25d50 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
25d60 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
25d70 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
25d80 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
25d90 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
25da0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
25db0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
25dc0 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
25dd0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
25de0 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
25df0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
25e00 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
25e10 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
25e20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
25e30 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
25e40 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
25e50 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
25e60 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
25e70 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
25e80 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
25e90 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
25ea0 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
25eb0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
25ec0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
25ed0 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
25ee0 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
25ef0 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
25f00 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
25f10 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
25f20 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
25f30 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
25f40 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
25f50 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
25f60 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
25f70 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
25f80 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
25f90 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
25fa0 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
25fb0 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
25fc0 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
25fd0 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
25fe0 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
25ff0 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
26000 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
26010 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
26020 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
26030 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
26040 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
26050 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
26060 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
26070 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
26080 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
26090 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
260a0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
260b0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
260c0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
260d0 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
260e0 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
260f0 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
26100 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
26110 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
26120 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
26130 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
26140 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
26150 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
26160 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
26170 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26180 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f  db?vfs=unix-nolo
26190 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  ck <td>.**      
261a0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
261b0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
261c0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
261d0 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f  ial VFS "unix-no
261e0 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  lock"..** <tr><t
261f0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
26200 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
26210 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26220 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
26230 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
26240 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
26250 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
26260 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
26270 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
26280 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
26290 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
262a0 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
262b0 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
262c0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
262d0 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
262e0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
262f0 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
26300 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
26310 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
26320 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
26330 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
26340 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
26350 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
26360 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
26370 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
26380 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
26390 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
263a0 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
263b0 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
263c0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
263d0 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
263e0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
263f0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
26400 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
26410 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
26420 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
26430 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
26440 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
26450 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
26460 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
26470 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
26480 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
26490 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
264a0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
264b0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
264c0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
264d0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
264e0 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
264f0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
26500 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
26510 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
26520 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
26530 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
26540 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
26550 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
26560 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
26570 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
26580 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
26590 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
265a0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
265b0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
265c0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
265d0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
265e0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
265f0 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
26600 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
26610 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
26620 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
26630 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
26640 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
26650 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
26660 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
26670 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
26680 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
26690 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
266a0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
266b0 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
266c0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
266d0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
266e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
266f0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
26700 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
26710 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
26720 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
26730 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
26740 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
26750 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
26760 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
26770 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
26780 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
26790 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
267a0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
267b0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
267c0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
267d0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
267e0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
267f0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
26800 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
26810 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
26820 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
26830 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
26840 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
26850 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
26860 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26870 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
26880 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
26890 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
268a0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
268b0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
268c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
268d0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
268e0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
268f0 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
26900 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
26910 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
26920 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
26930 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
26940 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
26950 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
26960 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
26970 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
26980 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
26990 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
269a0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
269b0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
269c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
269d0 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
269e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
269f0 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
26a00 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
26a10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26a20 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
26a30 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
26a40 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
26a50 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
26a60 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
26a70 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
26a80 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
26a90 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
26aa0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
26ab0 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
26ac0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
26ad0 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
26ae0 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
26af0 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
26b00 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
26b10 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
26b20 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
26b30 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
26b40 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
26b50 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
26b60 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
26b70 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
26b80 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
26b90 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
26ba0 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
26bb0 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
26bc0 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
26bd0 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
26be0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
26bf0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
26c00 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
26c10 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
26c20 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
26c30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
26c40 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
26c50 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
26c60 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
26c70 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
26c80 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
26c90 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
26ca0 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
26cb0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
26cc0 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
26cd0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
26ce0 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
26cf0 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
26d00 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
26d10 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
26d20 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
26d30 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
26d40 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
26d50 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
26d60 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
26d70 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
26d80 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
26d90 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
26da0 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
26db0 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
26dc0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
26dd0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
26de0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
26df0 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
26e00 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
26e10 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
26e20 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
26e30 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
26e40 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
26e50 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
26e60 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
26e70 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
26e80 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
26e90 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
26ea0 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
26eb0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
26ec0 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
26ed0 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
26ee0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
26ef0 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
26f00 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
26f10 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
26f20 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
26f30 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
26f40 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
26f50 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
26f60 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
26f70 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
26f80 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
26f90 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
26fa0 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
26fb0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
26fc0 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
26fd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
26fe0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
26ff0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
27000 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
27010 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
27020 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
27030 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
27040 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
27050 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
27060 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
27070 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
27080 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
27090 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
270a0 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
270b0 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
270c0 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
270d0 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
270e0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
270f0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
27100 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
27110 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
27120 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
27130 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
27140 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
27150 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49  r *zParam);.SQLI
27160 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27170 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
27180 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
27190 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
271a0 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
271b0 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  lt);.SQLITE_API 
271c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
271d0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
271e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
271f0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
27200 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
27210 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
27220 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
27230 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
27240 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
27250 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27260 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
27270 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
27280 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
27290 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
272a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
272b0 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
272c0 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
272d0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
272e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
272f0 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
27300 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
27310 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
27320 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
27330 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
27340 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
27350 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
27360 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
27370 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
27380 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
27390 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
273a0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
273b0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
273c0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
273d0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
273e0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
273f0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
27400 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
27410 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
27420 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
27430 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
27440 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
27450 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
27460 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
27470 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
27480 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
27490 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
274a0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
274b0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
274c0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
274d0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
274e0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
274f0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
27500 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
27510 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
27520 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
27530 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
27540 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
27550 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
27560 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
27570 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
27580 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
27590 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
275a0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
275b0 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
275c0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
275d0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
275e0 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
275f0 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
27600 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
27610 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
27620 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
27630 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
27640 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
27650 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
27660 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
27670 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
27680 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
27690 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
276a0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
276b0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
276c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
276d0 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
276e0 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
276f0 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
27700 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
27710 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
27720 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
27730 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
27740 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
27750 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
27760 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
27770 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
27780 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
27790 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
277a0 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
277b0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
277c0 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
277d0 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
277e0 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
277f0 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
27800 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
27810 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
27820 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
27830 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
27840 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
27850 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
27860 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
27870 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
27880 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
27890 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
278a0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
278b0 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
278c0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
278d0 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
278e0 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
278f0 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
27900 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
27910 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
27920 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
27930 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
27940 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
27950 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
27960 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
27970 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
27980 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
27990 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
279a0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
279b0 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
279c0 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49   be set..*/.SQLI
279d0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
279e0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
279f0 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
27a00 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
27a10 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
27a20 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53  (sqlite3 *db);.S
27a30 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
27a40 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
27a50 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
27a60 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
27a70 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
27a80 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
27a90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
27aa0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
27ab0 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
27ac0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27ad0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
27ae0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
27af0 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
27b00 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
27b10 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
27b20 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
27b30 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
27b40 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
27b50 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
27b60 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
27b70 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
27b80 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
27b90 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
27ba0 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53  a.** "compiled S
27bb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
27bc0 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
27bd0 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20  atement"..**.** 
27be0 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
27bf0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
27c00 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
27c10 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
27c20 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
27c30 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
27c40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
27c50 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
27c60 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
27c70 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
27c80 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
27c90 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   [host parameter
27ca0 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
27cb0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
27cc0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
27cd0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
27ce0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
27cf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27d00 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
27d10 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
27d20 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
27d30 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27d40 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
27d50 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
27d60 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
27d70 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
27d80 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
27d90 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
27da0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27db0 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
27dc0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
27dd0 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
27de0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
27df0 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
27e00 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
27e10 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
27e20 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
27e30 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
27e40 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
27e50 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
27e60 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a  time Limits.**.*
27e70 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
27e80 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
27e90 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
27ea0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
27eb0 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
27ec0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
27ed0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
27ee0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
27ef0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
27f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27f10 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
27f20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
27f30 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
27f40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
27f50 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
27f60 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
27f70 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
27f80 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
27f90 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
27fa0 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
27fb0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
27fc0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
27fd0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
27fe0 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
27ff0 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
28000 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
28010 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
28020 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
28030 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
28040 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
28050 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
28060 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
28070 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
28080 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
28090 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
280a0 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
280b0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
280c0 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
280d0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
280e0 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
280f0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
28100 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
28110 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
28120 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
28130 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
28140 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
28150 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
28160 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
28170 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
28180 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
28190 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
281a0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
281b0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
281c0 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
281d0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
281e0 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
281f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
28200 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
28210 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
28220 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
28230 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
28240 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
28250 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
28260 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
28270 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
28280 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
28290 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
282a0 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
282b0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
282c0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
282d0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
282e0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
282f0 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
28300 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
28310 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
28320 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
28330 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
28340 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
28350 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
28360 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
28370 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
28380 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
28390 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
283a0 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
283b0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
283c0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
283d0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
283e0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
283f0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
28400 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
28410 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
28420 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
28430 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
28440 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
28450 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
28460 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
28470 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
28480 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
28490 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
284a0 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
284b0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
284c0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
284d0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
284e0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
284f0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
28500 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
28510 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
28520 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
28530 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
28540 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
28550 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
28560 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
28570 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
28580 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
28590 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
285a0 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
285b0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
285c0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
285d0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
285e0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
285f0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
28600 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ases..*/.SQLITE_
28610 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
28620 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
28630 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
28640 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
28650 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
28660 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
28670 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
28680 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
28690 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
286a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
286b0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
286c0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
286d0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
286e0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
286f0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
28700 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
28710 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
28720 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
28730 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
28740 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
28750 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
28760 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
28770 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
28780 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
28790 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
287a0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
287b0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
287c0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
287d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
287e0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
287f0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
28800 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
28810 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
28820 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
28830 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
28840 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
28850 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
28860 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
28870 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
28880 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
28890 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
288a0 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
288b0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
288c0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
288d0 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
288e0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
288f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
28900 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
28910 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
28920 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
28930 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
28940 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
28950 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
28960 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
28970 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
28980 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
28990 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
289a0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
289b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
289c0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
289d0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
289e0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
289f0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
28a00 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
28a10 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
28a20 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
28a30 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
28a40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28a50 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
28a60 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
28a70 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
28a80 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
28a90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28aa0 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
28ab0 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
28ac0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
28ad0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
28ae0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
28af0 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
28b00 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
28b10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
28b20 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
28b30 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
28b40 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
28b50 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
28b60 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
28b70 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
28b80 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
28b90 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
28ba0 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
28bb0 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
28bc0 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
28bd0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
28be0 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
28bf0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
28c00 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
28c10 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
28c20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
28c30 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
28c40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28c50 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
28c60 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
28c70 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
28c80 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28c90 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
28ca0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
28cb0 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
28cc0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
28cd0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
28ce0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
28cf0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
28d00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28d10 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
28d20 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
28d30 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28d40 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
28d50 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
28d60 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
28d70 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
28d80 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
28d90 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
28da0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
28db0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
28dc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
28dd0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
28de0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
28df0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
28e00 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
28e10 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
28e20 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
28e30 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
28e40 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
28e50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
28e60 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
28e70 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
28e80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
28e90 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
28ea0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28eb0 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
28ec0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
28ed0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
28ee0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
28ef0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
28f00 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
28f10 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
28f20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
28f30 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
28f40 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
28f50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
28f60 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
28f70 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
28f80 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
28f90 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
28fa0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
28fb0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
28fc0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
28fd0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
28fe0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
28ff0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
29000 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
29010 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29020 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
29030 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
29040 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29050 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
29060 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
29070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29080 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
29090 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
290a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
290b0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
290c0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
290d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
290e0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
290f0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
29100 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29110 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
29120 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
29130 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
29140 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
29150 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
29160 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
29170 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
29180 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
29190 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
291a0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
291b0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
291c0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
291d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
291e0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
291f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29200 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
29210 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
29220 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
29230 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
29240 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
29250 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
29260 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
29270 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
29280 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
29290 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
292a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
292b0 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
292c0 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
292d0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
292e0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
292f0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
29300 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
29310 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
29320 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
29330 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
29340 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
29350 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
29360 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
29370 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29380 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
29390 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
293a0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
293b0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
293c0 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
293d0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
293e0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
293f0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
29400 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
29410 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
29420 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
29430 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
29440 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
29450 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
29460 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
29470 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
29480 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
29490 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
294a0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
294b0 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
294c0 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
294d0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
294e0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
294f0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
29500 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
29510 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
29520 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
29530 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
29540 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
29550 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
29560 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
29570 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
29580 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
29590 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
295a0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
295b0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
295c0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
295d0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
295e0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
295f0 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
29600 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
29610 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
29620 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
29630 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
29640 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
29650 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
29660 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
29670 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
29680 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
29690 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
296a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
296b0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
296c0 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
296d0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
296e0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
296f0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
29700 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
29710 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
29720 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
29730 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
29740 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
29750 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
29760 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29770 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
29780 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
29790 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
297a0 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
297b0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
297c0 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
297d0 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
297e0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
297f0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
29800 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
29810 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
29820 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
29830 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
29840 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
29850 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
29860 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
29870 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
29880 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
29890 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
298a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
298b0 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
298c0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
298d0 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
298e0 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
298f0 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
29900 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
29910 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
29920 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
29930 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
29940 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
29950 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
29960 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
29970 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
29980 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
29990 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
299a0 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
299b0 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
299c0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
299d0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
299e0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
299f0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
29a00 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
29a10 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
29a20 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
29a30 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
29a40 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
29a50 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
29a60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
29a70 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
29a80 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
29a90 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
29aa0 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
29ab0 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
29ac0 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
29ad0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
29ae0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
29af0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
29b00 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
29b10 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
29b20 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
29b30 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
29b40 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
29b50 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
29b60 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
29b70 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
29b80 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
29b90 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
29ba0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
29bb0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
29bc0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
29bd0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
29be0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
29bf0 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
29c00 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
29c10 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
29c20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29c30 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
29c40 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
29c50 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
29c60 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
29c70 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
29c80 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
29c90 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
29ca0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
29cb0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
29cc0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
29cd0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
29ce0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
29cf0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
29d00 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
29d10 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
29d20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
29d30 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
29d40 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
29d50 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
29d60 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
29d70 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
29d80 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
29d90 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
29da0 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
29db0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
29dc0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
29dd0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
29de0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
29df0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
29e00 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
29e10 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
29e20 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
29e30 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
29e40 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
29e50 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
29e60 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
29e70 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
29e80 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
29e90 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
29ea0 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
29eb0 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
29ec0 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
29ed0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
29ee0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
29ef0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
29f00 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
29f10 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
29f20 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
29f30 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
29f40 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
29f50 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
29f60 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
29f70 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
29f80 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
29f90 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
29fa0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
29fb0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
29fc0 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
29fd0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
29fe0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
29ff0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
2a000 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2a010 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
2a020 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
2a030 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
2a040 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
2a050 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2a060 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
2a070 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
2a080 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ol>.*/.SQLI
2a090 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2a0a0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
2a0b0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2a0c0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2a0d0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2a0e0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2a0f0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2a100 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2a110 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2a120 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2a130 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2a140 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2a150 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2a160 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2a170 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2a180 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2a190 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2a1a0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2a1b0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2a1c0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2a1d0 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
2a1e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2a1f0 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
2a200 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2a210 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2a220 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2a230 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2a240 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2a250 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2a260 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2a270 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2a280 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2a290 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2a2a0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2a2b0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2a2c0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2a2d0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2a2e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2a2f0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2a300 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2a310 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2a320 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
2a330 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2a340 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
2a350 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2a360 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2a370 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2a380 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2a390 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2a3a0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2a3b0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2a3c0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2a3d0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2a3e0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2a3f0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2a400 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2a410 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2a420 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2a430 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2a440 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2a450 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2a460 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2a470 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
2a480 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2a490 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2a4a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2a4b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2a4c0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2a4d0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2a4e0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2a4f0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2a500 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
2a510 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2a520 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2a530 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2a540 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2a550 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2a560 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2a570 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2a580 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2a590 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2a5a0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2a5b0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2a5c0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2a5d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a5e0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
2a5f0 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
2a600 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
2a610 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
2a620 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
2a630 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
2a640 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
2a650 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
2a660 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2a670 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
2a680 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
2a690 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
2a6a0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2a6b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2a6c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a6d0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  16_v2()]..*/.SQL
2a6e0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2a6f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
2a700 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2a710 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2a720 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2a730 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
2a740 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
2a750 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
2a760 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2a770 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
2a780 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2a790 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
2a7a0 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
2a7b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a7c0 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
2a7d0 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
2a7e0 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
2a7f0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
2a800 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
2a810 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
2a820 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2a830 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
2a840 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
2a850 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
2a860 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2a870 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
2a880 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
2a890 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2a8a0 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
2a8b0 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
2a8c0 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
2a8d0 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
2a8e0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
2a8f0 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
2a900 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
2a910 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
2a920 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2a930 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
2a940 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
2a950 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
2a960 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
2a970 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
2a980 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
2a990 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
2a9a0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
2a9b0 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
2a9c0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
2a9d0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
2a9e0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2a9f0 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
2aa00 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2aa10 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
2aa20 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
2aa30 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
2aa40 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
2aa50 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
2aa60 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
2aa70 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
2aa80 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
2aa90 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
2aaa0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2aab0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2aac0 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
2aad0 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
2aae0 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
2aaf0 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
2ab00 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2ab10 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
2ab20 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
2ab30 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
2ab40 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
2ab50 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
2ab60 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
2ab70 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
2ab80 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
2ab90 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
2aba0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2abb0 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
2abc0 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
2abd0 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
2abe0 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
2abf0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
2ac00 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
2ac10 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
2ac20 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
2ac30 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
2ac40 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2ac50 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
2ac60 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  sk..*/.SQLITE_AP
2ac70 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
2ac80 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
2ac90 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2aca0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2acb0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2acc0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2acd0 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
2ace0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
2acf0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2ad00 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
2ad10 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2ad20 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
2ad30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ad40 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
2ad50 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
2ad60 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
2ad70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2ad80 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75  ] but has not ru
2ad90 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
2ada0 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a  and/or has not .
2adb0 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
2adc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2add0 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
2ade0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2adf0 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
2ae00 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
2ae10 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
2ae20 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
2ae30 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
2ae40 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
2ae50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2ae60 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
2ae70 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2ae80 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
2ae90 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2aea0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2aeb0 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
2aec0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2aed0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2aee0 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
2aef0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2af00 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
2af10 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
2af20 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
2af30 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
2af40 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
2af50 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
2af60 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
2af70 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
2af80 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
2af90 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
2afa0 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
2afb0 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
2afc0 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
2afd0 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
2afe0 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
2aff0 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c  ion open..*/.SQL
2b000 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2b010 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71  te3_stmt_busy(sq
2b020 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2b030 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2b040 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
2b050 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
2b060 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
2b070 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b080 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
2b090 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
2b0a0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
2b0b0 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
2b0c0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
2b0d0 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
2b0e0 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
2b0f0 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
2b100 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
2b110 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
2b120 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
2b130 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
2b140 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
2b150 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
2b160 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
2b170 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
2b180 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
2b190 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
2b1a0 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
2b1b0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
2b1c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2b1d0 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
2b1e0 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
2b1f0 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
2b200 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
2b210 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
2b220 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b230 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
2b240 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
2b250 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
2b260 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
2b270 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b280 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
2b290 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
2b2a0 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
2b2b0 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
2b2c0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
2b2d0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
2b2e0 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
2b2f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b300 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
2b310 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
2b320 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
2b330 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
2b340 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
2b350 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
2b360 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
2b370 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
2b380 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2b390 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b3a0 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
2b3b0 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
2b3c0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2b3d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b3e0 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
2b3f0 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
2b400 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
2b410 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
2b420 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
2b430 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2b440 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
2b450 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
2b460 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
2b470 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
2b480 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
2b490 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
2b4a0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
2b4b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
2b4c0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
2b4d0 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
2b4e0 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
2b4f0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
2b500 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
2b510 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2b520 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
2b530 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
2b540 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
2b550 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
2b560 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
2b570 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
2b580 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
2b590 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
2b5a0 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
2b5b0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2b5c0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2b5d0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2b5e0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2b5f0 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
2b600 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
2b610 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
2b620 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2b630 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
2b640 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
2b650 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
2b660 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
2b670 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
2b680 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2b690 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
2b6a0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
2b6b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2b6c0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2b6d0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2b6e0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2b6f0 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
2b700 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
2b710 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2b720 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
2b730 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
2b740 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2b750 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2b760 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
2b770 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
2b780 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
2b790 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2b7a0 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
2b7b0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2b7c0 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
2b7d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2b7e0 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
2b7f0 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
2b800 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
2b810 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
2b820 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
2b830 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
2b840 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
2b850 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
2b860 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
2b870 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
2b880 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
2b890 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
2b8a0 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
2b8b0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
2b8c0 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
2b8d0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
2b8e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b8f0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2b900 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
2b910 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2b920 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
2b930 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
2b940 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
2b950 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
2b960 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
2b970 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
2b980 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
2b990 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2b9a0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2b9b0 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
2b9c0 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
2b9d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2b9e0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
2b9f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2ba00 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
2ba10 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
2ba20 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
2ba30 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2ba40 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
2ba50 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
2ba60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
2ba70 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
2ba80 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2ba90 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
2baa0 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
2bab0 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
2bac0 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
2bad0 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
2bae0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
2baf0 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
2bb00 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
2bb10 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a  ter binding}.**.
2bb20 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
2bb30 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
2bb40 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
2bb50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2bb60 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
2bb70 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
2bb80 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
2bb90 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
2bba0 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
2bbb0 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
2bbc0 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
2bbd0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
2bbe0 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
2bbf0 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
2bc00 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
2bc10 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
2bc20 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
2bc30 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
2bc40 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
2bc50 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
2bc60 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
2bc70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
2bc80 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
2bc90 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
2bca0 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
2bcb0 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
2bcc0 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
2bcd0 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
2bce0 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
2bcf0 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
2bd00 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
2bd10 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2bd20 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
2bd30 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
2bd40 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2bd50 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2bd60 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
2bd70 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
2bd80 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
2bd90 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
2bda0 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
2bdb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2bdc0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
2bdd0 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
2bde0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
2bdf0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2be00 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
2be10 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
2be20 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
2be30 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
2be40 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2be50 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
2be60 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
2be70 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
2be80 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
2be90 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
2bea0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
2beb0 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
2bec0 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
2bed0 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
2bee0 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
2bef0 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
2bf00 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
2bf10 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
2bf20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2bf30 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2bf40 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
2bf50 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
2bf60 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
2bf70 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
2bf80 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
2bf90 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
2bfa0 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
2bfb0 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
2bfc0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
2bfd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
2bfe0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2bff0 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
2c000 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
2c010 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2c020 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
2c030 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
2c040 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
2c050 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  r..**.** ^(In th
2c060 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
2c070 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
2c080 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
2c090 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2c0a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2c0b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
2c0c0 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
2c0d0 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
2c0e0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
2c0f0 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
2c100 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
2c110 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2c120 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
2c130 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2c140 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2c150 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2c160 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2c170 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
2c180 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
2c190 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
2c1a0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
2c1b0 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
2c1c0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2c1d0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
2c1e0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2c1f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2c200 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2c210 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
2c220 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
2c230 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2c240 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
2c250 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
2c260 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
2c270 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2c280 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
2c290 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2c2a0 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72  () then that par
2c2b0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
2c2c0 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
2c2d0 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
2c2e0 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
2c2f0 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
2c300 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
2c310 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
2c320 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
2c330 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
2c340 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
2c350 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
2c360 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
2c370 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2c380 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
2c390 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
2c3a0 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
2c3b0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
2c3c0 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
2c3d0 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
2c3e0 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
2c3f0 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
2c400 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
2c410 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
2c420 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2c430 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2c440 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
2c450 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
2c460 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2c470 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
2c480 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
2c490 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2c4a0 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
2c4b0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
2c4c0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
2c4d0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2c4e0 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
2c4f0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2c500 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
2c510 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
2c520 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2c530 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  blob(),.** sqlit
2c540 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
2c550 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2c560 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20  text16() fails. 
2c570 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66   .** ^If the fif
2c580 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
2c590 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
2c5a0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
2c5b0 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
2c5c0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2c5d0 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
2c5e0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
2c5f0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
2c600 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
2c610 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
2c620 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2c630 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
2c640 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
2c650 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
2c660 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
2c670 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
2c680 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
2c690 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
2c6a0 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
2c6b0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2c6c0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
2c6d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c6e0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
2c6f0 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
2c700 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
2c710 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
2c720 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
2c730 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
2c740 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
2c750 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
2c760 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
2c770 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
2c780 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
2c790 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
2c7a0 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
2c7b0 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
2c7c0 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
2c7d0 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
2c7e0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
2c7f0 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
2c800 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
2c810 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
2c820 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
2c830 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
2c840 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
2c850 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
2c860 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
2c870 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
2c880 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
2c890 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2c8a0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
2c8b0 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
2c8c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2c8d0 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2c8e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
2c8f0 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
2c900 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
2c910 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
2c920 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
2c930 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
2c940 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
2c950 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
2c960 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
2c970 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
2c980 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
2c990 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
2c9a0 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
2c9b0 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
2c9c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c9d0 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
2c9e0 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
2c9f0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2ca00 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2ca10 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
2ca20 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
2ca30 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
2ca40 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2ca50 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
2ca60 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
2ca70 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
2ca80 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
2ca90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2caa0 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
2cab0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2cac0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
2cad0 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
2cae0 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
2caf0 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
2cb00 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
2cb10 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
2cb20 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
2cb30 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2cb40 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
2cb50 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
2cb60 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
2cb70 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
2cb80 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2cb90 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2cba0 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
2cbb0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2cbc0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
2cbd0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2cbe0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2cbf0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2cc00 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2cc10 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2cc20 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2cc30 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
2cc40 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2cc50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2cc60 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
2cc70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2cc80 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
2cc90 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2cca0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
2ccb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ccc0 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t, int);.SQLITE_
2ccd0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2cce0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
2ccf0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
2cd00 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53  qlite3_int64);.S
2cd10 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2cd20 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2cd30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2cd40 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2cd50 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2cd60 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2cd70 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2cd80 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
2cd90 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2cda0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2cdb0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2cdc0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2cdd0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2cde0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2cdf0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2ce00 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2ce10 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
2ce20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2ce30 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
2ce40 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
2ce50 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2ce60 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
2ce70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2ce80 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
2ce90 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2cea0 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
2ceb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2cec0 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
2ced0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
2cee0 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
2cef0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
2cf00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cf10 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
2cf20 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
2cf30 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
2cf40 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
2cf50 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
2cf60 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
2cf70 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
2cf80 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
2cf90 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
2cfa0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
2cfb0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
2cfc0 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
2cfd0 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
2cfe0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2cff0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
2d000 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2d010 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
2d020 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
2d030 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
2d040 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
2d050 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
2d060 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
2d070 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
2d080 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
2d090 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2d0a0 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
2d0b0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
2d0c0 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
2d0d0 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
2d0e0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2d0f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2d100 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2d110 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2d120 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2d130 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2d140 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2d150 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2d160 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2d170 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2d180 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
2d190 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2d1a0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
2d1b0 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
2d1c0 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
2d1d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2d1e0 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
2d1f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d200 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
2d210 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
2d220 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2d230 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d240 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
2d250 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2d260 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
2d270 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2d280 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2d290 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
2d2a0 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
2d2b0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2d2c0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2d2d0 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
2d2e0 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
2d2f0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
2d300 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
2d310 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
2d320 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
2d330 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
2d340 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
2d350 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2d360 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
2d370 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
2d380 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
2d390 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
2d3a0 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
2d3b0 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
2d3c0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
2d3d0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
2d3e0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
2d3f0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
2d400 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
2d410 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
2d420 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
2d430 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
2d440 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
2d450 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
2d460 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
2d470 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2d480 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
2d490 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
2d4a0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
2d4b0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
2d4c0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
2d4d0 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
2d4e0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
2d4f0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
2d500 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2d510 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2d520 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2d530 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2d540 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2d550 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2d560 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2d570 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2d580 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2d590 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2d5a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2d5b0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2d5c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2d5d0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2d5e0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2d5f0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2d600 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2d610 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2d620 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2d630 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
2d640 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
2d650 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
2d660 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
2d670 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
2d680 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
2d690 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
2d6a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2d6b0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2d6c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
2d6d0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
2d6e0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
2d6f0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
2d700 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
2d710 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
2d720 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
2d730 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
2d740 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
2d750 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
2d760 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
2d770 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
2d780 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d790 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2d7a0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2d7b0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2d7c0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2d7d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2d7e0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2d7f0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2d800 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2d810 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2d820 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2d830 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2d840 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
2d850 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
2d860 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
2d870 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d880 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
2d890 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
2d8a0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2d8b0 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
2d8c0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
2d8d0 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
2d8e0 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
2d8f0 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
2d900 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2d910 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
2d920 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d930 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
2d940 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
2d950 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
2d960 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
2d970 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2d980 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
2d990 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2d9a0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2d9b0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2d9c0 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
2d9d0 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2d9e0 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2d9f0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2da00 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2da10 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2da20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2da30 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
2da40 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2da50 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
2da60 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
2da70 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
2da80 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
2da90 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
2daa0 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
2dab0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2dac0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2dad0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2dae0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2daf0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
2db00 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2db10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2db20 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
2db30 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
2db40 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2db50 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
2db60 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
2db70 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
2db80 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
2db90 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2dba0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2dbb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2dbc0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
2dbd0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2dbe0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2dbf0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2dc00 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2dc10 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2dc20 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
2dc30 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2dc40 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2dc50 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
2dc60 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
2dc70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2dc80 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2dc90 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
2dca0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
2dcb0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2dcc0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2dcd0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
2dce0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
2dcf0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
2dd00 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
2dd10 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
2dd20 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
2dd30 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
2dd40 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
2dd50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2dd60 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
2dd70 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
2dd80 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2dd90 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2dda0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2ddb0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2ddc0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2ddd0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2dde0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2ddf0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2de00 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
2de10 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
2de20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2de30 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
2de40 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2de50 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
2de60 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
2de70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
2de80 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
2de90 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
2dea0 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
2deb0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
2dec0 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
2ded0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
2dee0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
2def0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2df00 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2df10 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
2df20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
2df30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2df40 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
2df50 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
2df60 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
2df70 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
2df80 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
2df90 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
2dfa0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
2dfb0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
2dfc0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
2dfd0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
2dfe0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2dff0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
2e000 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2e010 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2e020 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
2e030 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2e040 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2e050 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2e060 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2e070 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e080 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2e090 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2e0a0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2e0b0 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2e0c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2e0d0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2e0e0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2e0f0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2e100 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2e110 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2e120 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2e130 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2e140 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2e150 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2e160 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2e170 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2e180 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2e190 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2e1a0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2e1b0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2e1c0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2e1d0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2e1e0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2e1f0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2e200 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2e210 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2e220 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2e230 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2e240 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2e250 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2e260 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2e270 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2e280 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2e290 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2e2a0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2e2b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2e2c0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2e2d0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2e2e0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2e2f0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2e300 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2e310 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2e320 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2e330 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2e340 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2e350 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2e360 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2e370 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2e380 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2e390 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2e3a0 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2e3b0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2e3c0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2e3d0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2e3e0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2e3f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2e400 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2e410 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2e420 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e430 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2e440 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2e450 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2e460 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2e470 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2e480 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2e490 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2e4a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2e4b0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2e4c0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2e4d0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2e4e0 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2e4f0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2e500 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2e510 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2e520 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2e530 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2e540 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2e550 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2e560 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2e570 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2e580 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2e590 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2e5a0 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2e5b0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2e5c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2e5d0 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2e5e0 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2e5f0 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2e600 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2e610 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2e620 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2e630 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2e640 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2e650 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2e660 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2e670 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2e680 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2e690 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2e6a0 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2e6b0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2e6c0 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2e6d0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2e6e0 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2e6f0 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2e700 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2e710 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2e720 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2e730 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2e740 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2e750 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2e760 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2e770 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2e780 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2e790 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2e7a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2e7b0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2e7c0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2e7d0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2e7e0 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2e7f0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2e800 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2e810 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2e820 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2e830 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2e840 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2e850 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2e860 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2e870 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2e880 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2e890 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2e8a0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2e8b0 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2e8c0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2e8d0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2e8e0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2e8f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2e900 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2e910 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2e920 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2e930 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2e940 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2e950 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2e960 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
2e970 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2e980 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2e990 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2e9a0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2e9b0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2e9c0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2e9d0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2e9e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2e9f0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
2ea00 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2ea10 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2ea20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2ea30 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2ea40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2ea50 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2ea60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2ea70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2ea80 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2ea90 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2eaa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2eab0 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
2eac0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
2ead0 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
2eae0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2eaf0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2eb00 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
2eb10 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
2eb20 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2eb30 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
2eb40 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
2eb50 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
2eb60 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
2eb70 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
2eb80 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
2eb90 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
2eba0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
2ebb0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
2ebc0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
2ebd0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
2ebe0 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
2ebf0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2ec00 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2ec10 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
2ec20 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
2ec30 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
2ec40 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2ec50 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2ec60 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
2ec70 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
2ec80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
2ec90 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
2eca0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2ecb0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
2ecc0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
2ecd0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
2ece0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
2ecf0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
2ed00 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
2ed10 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
2ed20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
2ed30 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
2ed40 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
2ed50 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
2ed60 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
2ed70 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
2ed80 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
2ed90 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
2eda0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
2edb0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
2edc0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
2edd0 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
2ede0 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
2edf0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
2ee00 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
2ee10 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
2ee20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
2ee30 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
2ee40 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
2ee50 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
2ee60 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
2ee70 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
2ee80 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
2ee90 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
2eea0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
2eeb0 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
2eec0 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
2eed0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2eee0 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
2eef0 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
2ef00 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
2ef10 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
2ef20 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c  e values..*/.SQL
2ef30 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2ef40 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2ef50 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
2ef60 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2ef70 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2ef80 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2ef90 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
2efa0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2efb0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2efc0 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
2efd0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2efe0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
2eff0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f000 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
2f010 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
2f020 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2f030 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2f040 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2f050 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
2f060 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
2f070 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
2f080 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
2f090 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2f0a0 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
2f0b0 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
2f0c0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
2f0d0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
2f0e0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
2f0f0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2f100 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
2f110 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
2f120 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
2f130 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
2f140 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
2f150 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
2f160 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
2f170 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
2f180 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
2f190 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2f1a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2f1b0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2f1c0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
2f1d0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
2f1e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2f1f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2f200 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
2f210 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
2f220 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
2f230 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2f240 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
2f250 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
2f260 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2f270 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
2f280 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
2f290 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
2f2a0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2f2b0 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
2f2c0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
2f2d0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
2f2e0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
2f2f0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
2f300 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2f310 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
2f320 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
2f330 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2f340 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
2f350 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
2f360 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
2f370 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
2f380 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2f390 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
2f3a0 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
2f3b0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2f3c0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
2f3d0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
2f3e0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
2f3f0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
2f400 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
2f410 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
2f420 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
2f430 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
2f440 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
2f450 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
2f460 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
2f470 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
2f480 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
2f490 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2f4a0 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
2f4b0 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
2f4c0 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
2f4d0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
2f4e0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
2f4f0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2f500 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
2f510 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
2f520 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
2f530 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
2f540 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
2f550 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
2f560 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2f570 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2f580 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2f590 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
2f5a0 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
2f5b0 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
2f5c0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
2f5d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
2f5e0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
2f5f0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
2f600 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2f610 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
2f620 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
2f630 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
2f640 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
2f650 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
2f660 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
2f670 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
2f680 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
2f690 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
2f6a0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
2f6b0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
2f6c0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
2f6d0 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
2f6e0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
2f6f0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
2f700 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2f710 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
2f720 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
2f730 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
2f740 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2f750 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
2f760 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
2f770 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
2f780 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
2f790 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
2f7a0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
2f7b0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2f7c0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2f7d0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
2f7e0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
2f7f0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
2f800 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2f810 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
2f820 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
2f830 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
2f840 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2f850 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
2f860 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
2f870 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
2f880 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
2f890 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
2f8a0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
2f8b0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
2f8c0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2f8d0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
2f8e0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2f8f0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
2f900 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2f910 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
2f920 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2f930 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
2f940 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
2f950 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
2f960 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
2f970 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2f980 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
2f990 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
2f9a0 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
2f9b0 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
2f9c0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
2f9d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2f9e0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
2f9f0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
2fa00 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2fa10 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
2fa20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
2fa30 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
2fa40 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
2fa50 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
2fa60 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
2fa70 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
2fa80 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
2fa90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2faa0 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
2fab0 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
2fac0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
2fad0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
2fae0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
2faf0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2fb00 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
2fb10 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
2fb20 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
2fb30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2fb40 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
2fb50 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
2fb60 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
2fb70 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
2fb80 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
2fb90 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
2fba0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
2fbb0 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
2fbc0 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
2fbd0 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
2fbe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2fbf0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2fc00 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
2fc10 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
2fc20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
2fc30 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
2fc40 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
2fc50 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
2fc60 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
2fc70 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
2fc80 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
2fc90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
2fca0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
2fcb0 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
2fcc0 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
2fcd0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2fce0 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
2fcf0 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
2fd00 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
2fd10 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
2fd20 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
2fd30 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
2fd40 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
2fd50 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
2fd60 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
2fd70 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
2fd80 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
2fd90 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
2fda0 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
2fdb0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
2fdc0 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
2fdd0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
2fde0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
2fdf0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
2fe00 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2fe10 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
2fe20 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
2fe30 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
2fe40 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
2fe50 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
2fe60 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
2fe70 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
2fe80 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
2fe90 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
2fea0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
2feb0 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
2fec0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2fed0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2fee0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
2fef0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
2ff00 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
2ff10 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
2ff20 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
2ff30 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
2ff40 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
2ff50 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
2ff60 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
2ff70 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
2ff80 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
2ff90 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
2ffa0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
2ffb0 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
2ffc0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
2ffd0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
2ffe0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2fff0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
30000 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
30010 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
30020 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
30030 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
30040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
30050 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
30060 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
30070 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
30080 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
30090 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
300a0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
300b0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
300c0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
300d0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
300e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
300f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
30100 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
30110 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30120 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
30130 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
30140 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
30150 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
30160 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
30170 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
30180 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
30190 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
301a0 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
301b0 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
301c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
301d0 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
301e0 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
301f0 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
30200 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
30210 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
30220 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
30230 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
30240 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
30250 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
30260 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
30270 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
30280 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
30290 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
302a0 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
302b0 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
302c0 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
302d0 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
302e0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
302f0 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
30300 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
30310 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
30320 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
30330 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
30340 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
30350 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
30360 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
30370 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
30380 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
30390 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
303a0 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
303b0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
303c0 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
303d0 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
303e0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
303f0 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
30400 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
30410 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
30420 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
30430 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
30440 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
30450 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
30460 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
30470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
30480 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
30490 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
304a0 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
304b0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
304c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
304d0 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
304e0 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
304f0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
30500 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
30510 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
30520 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
30530 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
30540 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
30550 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
30560 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
30570 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
30580 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
30590 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
305a0 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
305b0 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
305c0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
305d0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
305e0 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
305f0 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
30600 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
30610 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
30620 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
30630 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
30640 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
30650 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
30660 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
30670 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
30680 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
30690 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
306a0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
306b0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
306c0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
306d0 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
306e0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
306f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
30700 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
30710 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
30720 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
30730 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
30740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30750 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
30760 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
30770 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
30780 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
30790 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
307a0 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
307b0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
307c0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
307d0 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
307e0 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
307f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
30800 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
30810 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
30820 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
30830 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
30840 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  t" interface..**
30850 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
30860 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
30870 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
30880 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
30890 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
308a0 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
308b0 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
308c0 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
308d0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
308e0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
308f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30900 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
30910 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
30920 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
30930 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
30940 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
30950 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
30960 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
30970 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
30980 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
30990 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
309a0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
309b0 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
309c0 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
309d0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
309e0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
309f0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
30a00 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
30a10 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
30a20 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
30a30 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
30a40 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
30a50 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
30a60 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
30a70 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
30a80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
30a90 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
30aa0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
30ab0 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
30ac0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
30ad0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
30ae0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
30af0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
30b00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
30b10 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
30b20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
30b30 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
30b40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
30b50 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
30b60 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
30b70 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
30b80 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
30b90 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
30ba0 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
30bb0 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
30bc0 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
30bd0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
30be0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
30bf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30c00 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
30c10 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
30c20 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
30c30 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
30c40 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
30c50 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
30c60 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
30c70 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
30c80 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
30c90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
30ca0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30cb0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
30cc0 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
30cd0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
30ce0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
30cf0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
30d00 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
30d10 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
30d20 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
30d30 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
30d40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
30d50 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
30d60 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
30d70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
30d80 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
30d90 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
30da0 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
30db0 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
30dc0 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
30dd0 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
30de0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
30df0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
30e00 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
30e10 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
30e20 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
30e30 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
30e40 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
30e50 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
30e60 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
30e70 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
30e80 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
30e90 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
30ea0 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
30eb0 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
30ec0 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
30ed0 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
30ee0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
30ef0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
30f00 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
30f10 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
30f20 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
30f30 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
30f40 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
30f50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
30f60 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
30f70 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
30f80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
30f90 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
30fa0 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
30fb0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
30fc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
30fd0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
30fe0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
30ff0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
31000 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
31010 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
31020 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
31030 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
31040 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
31050 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
31060 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
31070 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
31080 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
31090 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
310a0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
310b0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
310c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
310d0 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
310e0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
310f0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
31100 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
31110 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
31120 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
31130 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
31140 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
31150 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
31160 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
31170 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31180 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
31190 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
311a0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
311b0 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
311c0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
311d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
311e0 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
311f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
31200 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
31210 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
31220 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
31230 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
31240 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
31250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31260 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
31270 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
31280 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
31290 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
312a0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
312b0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
312c0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
312d0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
312e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
312f0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
31300 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
31310 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
31320 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
31330 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
31340 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
31350 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
31360 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
31370 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
31380 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
31390 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
313a0 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
313b0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
313c0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
313d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
313e0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
313f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
31400 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
31410 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
31420 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
31430 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
31440 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
31450 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
31460 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
31470 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
31480 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
31490 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
314a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
314b0 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
314c0 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
314d0 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
314e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
314f0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
31500 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
31510 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
31520 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
31530 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
31540 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
31550 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
31560 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
31570 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
31580 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
31590 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
315a0 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
315b0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
315c0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
315d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62  r..**.** ^The ob
315e0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
315f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
31600 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
31610 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
31620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31630 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
31640 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
31650 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
31660 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
31670 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
31680 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
31690 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
316a0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
316b0 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
316c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
316d0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
316e0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
316f0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
31700 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
31710 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
31720 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
31730 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
31740 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
31750 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
31760 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
31770 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
31780 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
31790 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
317a0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
317b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
317c0 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
317d0 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
317e0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
317f0 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
31800 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
31810 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
31820 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
31830 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
31840 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
31850 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
31860 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
31870 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
31880 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
31890 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
318a0 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
318b0 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
318c0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
318d0 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
318e0 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
318f0 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
31900 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
31910 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
31920 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
31930 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
31940 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
31950 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
31960 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
31970 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
31980 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
31990 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
319a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
319b0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
319c0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
319d0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
319e0 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
319f0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
31a00 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
31a10 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
31a20 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
31a30 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
31a40 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
31a50 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
31a60 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
31a70 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
31a80 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
31a90 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
31aa0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
31ab0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
31ac0 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
31ad0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
31ae0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
31af0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
31b00 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
31b10 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
31b20 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
31b30 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
31b40 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
31b50 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
31b60 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
31b70 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
31b80 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
31b90 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
31ba0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
31bb0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
31bc0 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
31bd0 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
31be0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
31bf0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
31c00 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
31c10 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
31c20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
31c30 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
31c40 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
31c50 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
31c60 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
31c70 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
31c80 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
31c90 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
31ca0 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
31cb0 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
31cc0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
31cd0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
31ce0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
31cf0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
31d00 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
31d10 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
31d20 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
31d30 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
31d40 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
31d50 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
31d60 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
31d70 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
31d80 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
31d90 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
31da0 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
31db0 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
31dc0 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
31dd0 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
31de0 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
31df0 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
31e00 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
31e10 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
31e20 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
31e30 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
31e40 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
31e50 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
31e60 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
31e70 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
31e80 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
31e90 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
31ea0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
31eb0 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
31ec0 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
31ed0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
31ee0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
31ef0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
31f00 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
31f10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
31f20 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
31f30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
31f40 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
31f50 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
31f60 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
31f70 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
31f80 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
31f90 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
31fa0 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
31fb0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
31fc0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
31fd0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
31fe0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
31ff0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
32000 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
32010 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
32020 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
32030 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
32040 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
32050 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
32060 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
32070 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
32080 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
32090 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
320a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
320b0 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
320c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
320d0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
320e0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
320f0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
32100 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
32110 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
32120 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
32130 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
32140 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
32150 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32160 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
32170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
32180 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
32190 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
321a0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
321b0 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
321c0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
321d0 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
321e0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
321f0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
32200 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
32210 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
32220 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
32230 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
32240 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
32250 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
32260 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
32270 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
32280 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
32290 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
322a0 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
322b0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
322c0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
322d0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
322e0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
322f0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
32300 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
32310 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
32320 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
32330 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
32340 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
32350 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
32360 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
32370 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
32380 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
32390 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
323a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
323b0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
323c0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
323d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
323e0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
323f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32400 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
32410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
32420 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
32430 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32440 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
32450 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
32460 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
32470 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
32480 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32490 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
324a0 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
324b0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
324c0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
324d0 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
324e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
324f0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
32500 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
32510 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
32520 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
32530 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
32540 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
32550 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
32560 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
32570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32580 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
32590 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
325a0 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
325b0 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
325c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
325d0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
325e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
325f0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
32600 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32610 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
32620 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
32630 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
32640 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
32650 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
32660 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32670 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
32680 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
32690 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
326a0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
326b0 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
326c0 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
326d0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
326e0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
326f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
32700 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
32710 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
32720 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
32730 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
32740 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
32750 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
32760 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
32770 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
32780 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
32790 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
327a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
327b0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
327c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
327d0 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
327e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
327f0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
32800 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
32810 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
32820 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
32830 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
32840 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
32850 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
32860 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
32870 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
32880 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
32890 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
328a0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
328b0 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
328c0 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
328d0 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
328e0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
328f0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
32900 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
32910 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51  _NOMEM].)^.*/.SQ
32920 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
32930 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
32940 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
32950 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
32960 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
32970 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
32980 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
32990 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
329a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
329b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
329c0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
329d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
329e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
329f0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
32a00 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
32a10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
32a20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
32a30 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
32a40 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
32a50 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
32a60 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
32a70 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
32a80 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
32a90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
32aa0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
32ab0 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
32ac0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
32ad0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
32ae0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
32af0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
32b00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
32b10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
32b20 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
32b30 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
32b40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
32b50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
32b60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32b70 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
32b80 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  API sqlite3_valu
32b90 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
32ba0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
32bb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
32bc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32bd0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
32be0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
32bf0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Object.**.** ^Th
32c00 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
32c10 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
32c20 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
32c30 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
32c40 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
32c50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
32c60 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
32c70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
32c80 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
32c90 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
32ca0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
32cb0 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
32cc0 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
32cd0 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
32ce0 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
32cf0 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
32d00 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
32d10 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
32d20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
32d30 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
32d40 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
32d50 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
32d60 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
32d70 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
32d80 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
32d90 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
32da0 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
32db0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
32dc0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
32dd0 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
32de0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
32df0 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
32e00 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
32e10 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
32e20 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
32e30 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
32e40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
32e50 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
32e60 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
32e70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
32e80 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
32e90 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
32ea0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
32eb0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
32ec0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
32ed0 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
32ee0 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
32ef0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
32f00 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
32f10 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
32f20 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
32f30 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
32f40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
32f50 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
32f60 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
32f70 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
32f80 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
32f90 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32fa0 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
32fb0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
32fc0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
32fd0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
32fe0 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
32ff0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
33000 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
33010 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
33020 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
33030 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
33040 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
33050 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
33060 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
33070 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
33080 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
33090 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
330a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
330b0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
330c0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
330d0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
330e0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
330f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
33100 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
33110 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
33120 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
33130 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
33140 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
33150 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
33160 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
33170 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
33180 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
33190 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
331a0 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
331b0 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
331c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
331d0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
331e0 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
331f0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
33200 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
33210 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
33220 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
33230 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
33240 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
33250 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
33260 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
33270 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33280 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
33290 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
332a0 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
332b0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
332c0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
332d0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
332e0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
332f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33300 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
33310 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
33320 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
33330 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
33340 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
33350 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
33360 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
33370 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
33380 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
33390 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
333a0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
333b0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
333c0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
333d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
333e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
333f0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
33400 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
33410 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
33420 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
33430 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
33440 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
33450 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
33460 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
33470 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
33480 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
33490 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
334a0 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
334b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
334c0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51  tement] S..*/.SQ
334d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
334e0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
334f0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
33500 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33510 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
33520 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
33530 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
33540 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
33550 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
33560 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
33570 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
33580 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
33590 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
335a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
335b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
335c0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
335d0 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
335e0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
335f0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
33600 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
33610 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
33620 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
33630 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
33640 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
33650 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
33660 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
33670 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
33680 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
33690 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a  rences between.*
336a0 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * these routines
336b0 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e   are the text en
336c0 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20  coding expected 
336d0 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  for.** the secon
336e0 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  d parameter (the
336f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e   name of the fun
33700 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61  ction being crea
33710 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ted).** and the 
33720 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65  presence or abse
33730 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63  nce of a destruc
33740 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  tor callback for
33750 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
33760 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
33770 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
33780 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
33790 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
337a0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
337b0 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
337c0 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
337d0 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61  added.  ^If an a
337e0 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20  pplication uses 
337f0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
33800 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
33810 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63  tion then applic
33820 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
33830 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74  L functions must
33840 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20   be added.** to 
33850 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
33860 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74  nnection separat
33870 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ely..**.** ^The 
33880 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
33890 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
338a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
338b0 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
338c0 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
338d0 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
338e0 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
338f0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
33900 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72   in a UTF-8.** r
33910 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65  epresentation, e
33920 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
33930 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
33940 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65    ^Note that the
33950 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20   name.** length 
33960 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d  limit is in UTF-
33970 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61  8 bytes, not cha
33980 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d  racters nor UTF-
33990 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e  16 bytes.  .** ^
339a0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
339b0 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
339c0 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
339d0 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
339e0 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  lt in [SQLITE_MI
339f0 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75  SUSE] being retu
33a00 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
33a10 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
33a20 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68   (nArg).** is th
33a30 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
33a40 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
33a50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
33a60 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
33a70 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61  s. ^If this para
33a80 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65  meter is -1, the
33a90 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  n the SQL functi
33aa0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
33ab0 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20  te may take any 
33ac0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
33ad0 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e  nts between 0 an
33ae0 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73  d the limit.** s
33af0 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  et by [sqlite3_l
33b00 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
33b10 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
33b20 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72  ]).  If the thir
33b30 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
33b40 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f  s less than -1 o
33b50 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
33b60 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  27 then the beha
33b70 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66  vior is.** undef
33b80 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
33b90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
33ba0 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
33bb0 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
33bc0 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
33bd0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
33be0 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
33bf0 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
33c00 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45  s parameters.  E
33c10 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f  very SQL functio
33c20 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
33c30 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f   must be able to
33c40 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54   work.** with UT
33c50 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
33c60 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
33c70 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
33c80 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
33c90 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
33ca0 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
33cb0 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
33cc0 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ^An application 
33cd0 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71  may.** invoke sq
33ce0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33cf0 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
33d00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33d10 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
33d20 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
33d30 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
33d40 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
33d50 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
33d60 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20  xtRep..** ^When 
33d70 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
33d80 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
33d90 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
33da0 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
33db0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
33dc0 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
33dd0 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
33de0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
33df0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
33e00 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
33e10 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
33e20 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
33e30 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
33e40 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
33e50 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
33e60 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
33e70 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
33e80 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
33e90 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
33ea0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
33eb0 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
33ec0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
33ed0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
33ee0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
33ef0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
33f00 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
33f10 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
33f20 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
33f30 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
33f40 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
33f50 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
33f60 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
33f70 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
33f80 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
33f90 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
33fa0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
33fb0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
33fc0 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
33fd0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
33fe0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
33ff0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
34000 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
34010 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
34020 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
34030 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
34040 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
34050 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
34060 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
34070 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
34080 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
34090 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
340a0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
340b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
340c0 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
340d0 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
340e0 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
340f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
34100 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
34110 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
34120 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
34130 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
34140 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
34150 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
34160 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
34170 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
34180 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
34190 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
341a0 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
341b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
341c0 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
341d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
341e0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
341f0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
34200 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
34210 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
34220 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
34230 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
34240 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
34250 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
34260 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
34270 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
34280 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
34290 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
342a0 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
342b0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
342c0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
342d0 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
342e0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
342f0 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
34300 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
34310 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
34320 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34330 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
34340 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
34350 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
34360 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
34370 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
34380 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
34390 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
343a0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
343b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
343c0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
343d0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
343e0 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
343f0 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
34400 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
34410 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
34420 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
34430 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
34440 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
34450 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
34460 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
34470 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
34480 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
34490 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
344a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
344b0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
344c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
344d0 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
344e0 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
344f0 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
34500 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
34510 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
34520 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
34530 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
34540 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
34550 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
34560 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
34570 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
34580 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
34590 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
345a0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
345b0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
345c0 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
345d0 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
345e0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
345f0 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
34600 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
34610 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
34620 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
34630 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
34640 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
34650 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
34660 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
34670 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
34680 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
34690 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
346a0 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
346b0 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
346c0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
346d0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
346e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
346f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
34700 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
34710 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
34720 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
34730 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
34740 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
34750 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
34760 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
34770 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
34780 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
34790 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
347a0 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
347b0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
347c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
347d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
347e0 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
347f0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
34800 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
34810 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
34820 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
34830 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
34840 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
34850 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34860 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
34870 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
34880 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
34890 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
348a0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
348b0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
348c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
348d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
348e0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
348f0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
34900 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
34910 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
34920 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
34930 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
34940 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
34950 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
34960 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
34970 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
34980 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
34990 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
349a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
349b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
349c0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
349d0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
349e0 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  t*).);.SQLITE_AP
349f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
34a00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
34a10 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
34a20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
34a30 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
34a40 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
34a50 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
34a60 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
34a70 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
34a80 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
34a90 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
34aa0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
34ab0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34ac0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
34ad0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
34ae0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
34af0 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
34b00 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
34b10 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
34b20 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
34b30 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
34b40 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
34b50 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
34b60 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
34b70 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
34b80 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
34b90 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
34ba0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
34bb0 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
34bc0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
34bd0 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
34be0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
34bf0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
34c00 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
34c10 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
34c20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
34c30 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
34c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
34c50 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
34c60 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
34c70 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34c80 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
34c90 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
34ca0 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
34cb0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34cc0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
34cd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34ce0 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
34cf0 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
34d00 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
34d10 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
34d20 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
34d30 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
34d40 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
34d50 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
34d60 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
34d70 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
34d80 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
34d90 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
34da0 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
34db0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
34dc0 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
34dd0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
34de0 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
34df0 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
34e00 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
34e10 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
34e20 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
34e30 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
34e40 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
34e50 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
34e60 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
34e70 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
34e80 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
34e90 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34ea0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
34eb0 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
34ec0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
34ed0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
34ee0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
34ef0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
34f00 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
34f10 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
34f20 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
34f30 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
34f40 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
34f50 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
34f60 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
34f70 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
34f80 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
34f90 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
34fa0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
34fb0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
34fc0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
34fd0 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
34fe0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
34ff0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
35000 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
35010 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
35020 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
35030 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
35040 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
35050 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
35060 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
35070 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
35080 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
35090 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
350a0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
350b0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
350c0 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
350d0 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
350e0 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
350f0 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
35100 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
35110 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
35120 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
35130 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
35140 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
35150 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
35160 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
35170 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
35180 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35190 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
351a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
351b0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
351c0 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
351d0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
351e0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
351f0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
35200 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61  .** The 3rd para
35210 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
35220 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
35230 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
35240 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
35250 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
35260 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
35270 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
35280 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
35290 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
352a0 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
352b0 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
352c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
352d0 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
352e0 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
352f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
35300 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
35310 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
35320 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
35330 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
35340 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
35350 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
35360 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
35370 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
35380 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
35390 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
353a0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
353b0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
353c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
353d0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
353e0 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
353f0 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
35400 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
35410 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
35420 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
35430 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
35440 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35450 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
35460 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
35470 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
35480 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
35490 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
354a0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
354b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
354c0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
354d0 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
354e0 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
354f0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
35500 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
35510 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
35520 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
35530 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
35540 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
35550 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
35560 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
35570 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
35580 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
35590 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
355a0 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
355b0 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
355c0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
355d0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
355e0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
355f0 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
35600 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
35610 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
35620 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
35630 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
35640 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
35650 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
35660 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
35670 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
35680 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
35690 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
356a0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
356b0 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
356c0 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
356d0 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
356e0 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
356f0 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
35700 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
35710 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
35720 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
35730 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
35740 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
35750 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
35760 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
35770 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
35780 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
35790 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
357a0 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
357b0 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
357c0 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
357d0 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
357e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
357f0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
35800 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
35810 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
35820 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
35830 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
35840 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
35850 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
35860 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
35870 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
35880 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
35890 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
358a0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
358b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
358c0 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
358d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
358e0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
358f0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
35900 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
35910 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
35920 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
35930 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
35940 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eters..*/.SQLITE
35950 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
35960 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
35970 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
35980 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
35990 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
359a0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
359b0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
359c0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
359d0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
359e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
359f0 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65  QLITE_API double
35a00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
35a10 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
35a20 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
35a30 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
35a40 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
35a50 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
35a60 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
35a70 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
35a80 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
35a90 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
35aa0 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
35ab0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
35ac0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
35ad0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
35ae0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
35af0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
35b00 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
35b10 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
35b20 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
35b30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
35b40 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
35b50 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
35b60 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
35b70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
35b80 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
35b90 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
35ba0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
35bb0 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
35bc0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
35bd0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
35be0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
35bf0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
35c00 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
35c10 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
35c20 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
35c30 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
35c40 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
35c50 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
35c60 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
35c70 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
35c80 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
35c90 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
35ca0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
35cb0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
35cc0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
35cd0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
35ce0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
35cf0 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
35d00 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
35d10 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
35d20 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
35d30 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
35d40 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
35d50 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
35d60 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
35d70 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
35d80 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
35d90 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
35da0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
35db0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
35dc0 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
35dd0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
35de0 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
35df0 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
35e00 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
35e10 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
35e20 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
35e30 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
35e40 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
35e50 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
35e60 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
35e70 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
35e80 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
35e90 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
35ea0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
35eb0 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
35ec0 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
35ed0 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
35ee0 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
35ef0 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
35f00 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
35f10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
35f20 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
35f30 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
35f40 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
35f50 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
35f60 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
35f70 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
35f80 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
35f90 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
35fa0 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
35fb0 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
35fc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35fd0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
35fe0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
35ff0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
36000 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a  ointer if N is.*
36010 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  * less than or e
36020 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
36030 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
36040 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
36050 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
36060 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
36070 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
36080 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
36090 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
360a0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
360b0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
360c0 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
360d0 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
360e0 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
360f0 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
36100 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
36110 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
36120 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
36130 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
36140 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
36150 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
36160 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
36170 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
36180 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
36190 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
361a0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
361b0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
361c0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
361d0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
361e0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
361f0 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
36200 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
36210 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
36220 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
36230 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
36240 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
36250 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
36260 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
36270 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
36280 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
36290 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
362a0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
362b0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
362c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
362d0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
362e0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
362f0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
36300 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
36310 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
36320 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
36330 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
36340 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
36350 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
36360 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
36370 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
36380 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
36390 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
363a0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
363b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
363c0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
363d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
363e0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
363f0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
36400 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
36410 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
36420 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
36430 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
36440 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
36450 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
36460 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36470 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
36480 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
36490 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
364a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
364b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
364c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
364d0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
364e0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
364f0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
36500 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
36510 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36520 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
36530 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
36540 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
36550 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
36560 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
36570 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
36580 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
36590 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
365a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
365b0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
365c0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
365d0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
365e0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
365f0 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
36600 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
36610 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
36620 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
36630 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36640 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
36650 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36660 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
36670 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
36680 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
36690 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
366a0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
366b0 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  on..*/.SQLITE_AP
366c0 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  I sqlite3 *sqlit
366d0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
366e0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
366f0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
36700 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
36710 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
36720 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
36730 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
36740 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
36750 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
36760 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
36770 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
36780 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
36790 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
367a0 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
367b0 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
367c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
367d0 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
367e0 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
367f0 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
36800 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
36810 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
36820 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
36830 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
36840 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
36850 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
36860 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
36870 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
36880 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
36890 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
368a0 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
368b0 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
368c0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
368d0 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
368e0 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
368f0 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
36900 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
36910 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
36920 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
36930 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
36940 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
36950 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
36960 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
36970 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
36980 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
36990 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
369a0 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
369b0 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
369c0 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
369d0 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
369e0 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
369f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
36a00 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
36a10 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
36a20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
36a30 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
36a40 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
36a50 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
36a60 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
36a70 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
36a80 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
36a90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
36aa0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
36ab0 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20  ^If no metadata 
36ac0 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a  has been ever.**
36ad0 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68   been set for th
36ae0 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f  e Nth argument o
36af0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
36b00 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
36b10 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  ponding.** funct
36b20 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61  ion parameter ha
36b30 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
36b40 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
36b50 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73  s set,.** then s
36b60 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
36b70 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  ta() returns a N
36b80 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
36b90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36ba0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
36bb0 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
36bc0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
36bd0 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
36be0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
36bf0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
36c00 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
36c10 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
36c20 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
36c30 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
36c40 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
36c50 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
36c60 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
36c70 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
36c80 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
36c90 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
36ca0 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  d..** ^If it is 
36cb0 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
36cc0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
36cd0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
36ce0 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
36cf0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
36d00 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
36d10 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
36d20 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
36d30 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
36d40 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
36d50 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
36d60 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
36d70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
36d80 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
36d90 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
36da0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
36db0 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
36dc0 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
36dd0 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
36de0 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
36df0 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
36e00 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
36e10 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e  ^The only guaran
36e20 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74  tee is that.** t
36e30 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
36e40 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  ll be called bef
36e50 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61  ore the metadata
36e60 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a   is dropped..**.
36e70 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65  ** ^(In practice
36e80 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
36e90 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
36ea0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
36eb0 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
36ec0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
36ed0 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
36ee0 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
36ef0 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
36f00 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
36f10 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  ters].)^.**.** T
36f20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
36f30 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
36f40 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
36f50 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
36f60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
36f70 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
36f80 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
36f90 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
36fa0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
36fb0 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c  xt*, int N);.SQL
36fc0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
36fd0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
36fe0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36ff0 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
37000 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
37010 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
37020 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
37030 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
37040 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
37050 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ior.**.** These 
37060 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
37070 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
37080 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
37090 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
370a0 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
370b0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
370c0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
370d0 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20  t_blob()].  ^If 
370e0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
370f0 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
37100 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
37110 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
37120 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
37130 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
37140 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
37150 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
37160 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
37170 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a  troyed.  ^The.**
37180 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
37190 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
371a0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
371b0 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
371c0 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
371d0 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
371e0 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
371f0 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
37200 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
37210 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
37220 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
37230 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
37240 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
37250 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
37260 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
37270 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
37280 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31    See ticket #21
37290 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  91..*/.typedef v
372a0 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
372b0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
372c0 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
372d0 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
372e0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
372f0 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
37300 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
37310 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
37320 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
37330 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
37340 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
37350 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
37360 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
37370 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
37380 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
37390 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
373a0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
373b0 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
373c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
373d0 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
373e0 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
373f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
37400 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
37410 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
37420 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
37430 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
37440 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
37450 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
37460 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
37470 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
37480 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
37490 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
374a0 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
374b0 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
374c0 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
374d0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
374e0 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
374f0 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
37500 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
37510 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
37520 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
37530 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
37540 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
37550 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
37560 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
37570 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37580 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
37590 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
375a0 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
375b0 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
375c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
375d0 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
375e0 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
375f0 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
37600 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
37610 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
37620 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
37630 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
37640 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
37650 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37660 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37670 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
37680 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
37690 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
376a0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
376b0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
376c0 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
376d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
376e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
376f0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
37700 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
37710 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
37720 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
37730 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37740 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
37750 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
37760 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
37770 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
37780 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37790 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
377a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
377b0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
377c0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
377d0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
377e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
377f0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
37800 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ion..** ^SQLite 
37810 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
37820 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
37830 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
37840 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
37850 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
37860 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37870 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
37880 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
37890 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53  ror message.  ^S
378a0 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
378b0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
378c0 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
378d0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
378e0 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
378f0 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  8. ^SQLite.** in
37900 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
37910 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
37920 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
37930 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
37940 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
37950 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68  der.  ^If the th
37960 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
37970 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37980 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
37990 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
379a0 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
379b0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
379c0 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
379d0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
379e0 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
379f0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
37a00 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
37a10 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
37a20 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
37a30 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
37a40 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
37a50 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
37a60 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
37a70 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
37a80 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
37a90 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
37aa0 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
37ab0 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
37ac0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
37ad0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
37ae0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
37af0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
37b00 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
37b10 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
37b20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
37b30 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
37b40 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
37b50 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
37b60 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
37b70 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
37b80 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
37b90 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
37ba0 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
37bb0 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
37bc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37bd0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
37be0 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
37bf0 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
37c00 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
37c10 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
37c20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
37c30 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
37c40 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a  .  ^By default,.
37c50 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
37c60 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
37c70 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e  R.  ^A subsequen
37c80 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
37c90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
37ca0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
37cb0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
37cc0 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
37cd0 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
37ce0 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ERROR..**.** ^Th
37cf0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37d00 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20  _error_toobig() 
37d10 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
37d20 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
37d30 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
37d40 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
37d50 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
37d60 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
37d70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
37d80 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37d90 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20  t_error_nomem() 
37da0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
37db0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
37dc0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
37dd0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
37de0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
37df0 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
37e00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37e10 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
37e20 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
37e30 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
37e40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37e50 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37e60 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
37e70 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
37e80 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
37e90 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
37ea0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
37eb0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
37ec0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
37ed0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
37ee0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
37ef0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37f00 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
37f10 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
37f20 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
37f30 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
37f40 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
37f50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37f60 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
37f70 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
37f80 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
37f90 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
37fa0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37fb0 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
37fc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37fd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37fe0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
37ff0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
38000 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
38010 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
38020 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
38030 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
38040 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
38050 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
38060 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
38070 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
38080 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
38090 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
380a0 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
380b0 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
380c0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
380d0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
380e0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
380f0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
38100 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
38110 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
38120 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
38130 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
38140 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
38150 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
38160 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
38170 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
38180 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
38190 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
381a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
381b0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
381c0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
381d0 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
381e0 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
381f0 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
38200 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
38210 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
38220 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
38230 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
38240 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
38250 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
38260 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
38270 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
38280 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
38290 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
382a0 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
382b0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
382c0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
382d0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
382e0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
382f0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
38300 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
38310 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
38320 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
38330 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
38340 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
38350 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
38360 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
38370 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
38380 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
38390 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
383a0 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
383b0 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
383c0 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
383d0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
383e0 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
383f0 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
38400 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
38410 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
38420 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
38430 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
38440 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
38450 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
38460 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
38470 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
38480 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
38490 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
384a0 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
384b0 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
384c0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
384d0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
384e0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
384f0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
38500 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
38510 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
38520 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
38530 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
38540 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
38550 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
38560 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
38570 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
38580 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
38590 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
385a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
385b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
385c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
385d0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
385e0 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
385f0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
38600 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
38610 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
38620 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
38630 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
38640 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
38650 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
38660 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
38670 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
38680 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
38690 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
386a0 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
386b0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
386c0 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
386d0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
386e0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
386f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
38700 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
38710 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38720 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
38730 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
38740 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
38750 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
38760 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
38770 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
38780 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
38790 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
387a0 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to