System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 99caf1e4da238f358fe4bc1a77ae66806abc7ac1:


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 37 2e 20 20  ersion 3.7.17.  
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 23 69 66 20 64 65 66 69 6e 65  ndif..#if define
2840: 64 28 5f 5f 4f 70 65 6e 42 53 44 5f 5f 29 20 26  d(__OpenBSD__) &
2850: 26 20 21 64 65 66 69 6e 65 64 28 5f 42 53 44 5f  & !defined(_BSD_
2860: 53 4f 55 52 43 45 29 0a 23 20 64 65 66 69 6e 65  SOURCE).# define
2870: 20 5f 42 53 44 5f 53 4f 55 52 43 45 0a 23 65 6e   _BSD_SOURCE.#en
2880: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75  dif../*.** Inclu
2890: 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61 64  de standard head
28a0: 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63 65  er files as nece
28b0: 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66 20  ssary.*/.#ifdef 
28c0: 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23 69  HAVE_STDINT_H.#i
28d0: 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e 68  nclude <stdint.h
28e0: 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20  >.#endif.#ifdef 
28f0: 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48 0a  HAVE_INTTYPES_H.
2900: 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79 70  #include <inttyp
2910: 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  es.h>.#endif../*
2920: 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
2930: 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65  g macros are use
2940: 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74 65  d to cast pointe
2950: 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20 61  rs to integers a
2960: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 74  nd.** integers t
2970: 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68 65  o pointers.  The
2980: 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69 73   way you do this
2990: 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65   varies from one
29a0: 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20   compiler.** to 
29b0: 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65 20  the next, so we 
29c0: 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20 74  have developed t
29d0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 74  he following set
29e0: 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65 6e   of #if statemen
29f0: 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61 74  ts.** to generat
2a00: 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d 61  e appropriate ma
2a10: 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65 20  cros for a wide 
2a20: 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c 65  range of compile
2a30: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  rs..**.** The co
2a40: 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 61 79  rrect "ANSI" way
2a50: 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20 74   to do this is t
2a60: 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 74 72  o use the intptr
2a70: 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e 66  _t type. .** Unf
2a80: 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61 74  ortunately, that
2a90: 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74 20   typedef is not 
2aa0: 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c 6c  available on all
2ab0: 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a 2a   compilers, or.*
2ac0: 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 69 6c  * if it is avail
2ad0: 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72 65  able, it require
2ae0: 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f 66  s an #include of
2af0: 20 73 70 65 63 69 66 69 63 20 68 65 61 64 65 72   specific header
2b00: 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20 66  s.** that vary f
2b10: 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65 20  rom one machine 
2b20: 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a  to the next..**.
2b30: 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30 3a  ** Ticket #3860:
2b40: 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d 34    The llvm-gcc-4
2b50: 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f 6d  .2 compiler from
2b60: 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f 6e   Apple chokes on
2b70: 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a 29  .** the ((void*)
2b80: 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 20  &((char*)0)[X]) 
2b90: 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74 20  construct.  But 
2ba0: 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20 28  MSVC chokes on (
2bb0: 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a 20  (void*)(X))..** 
2bc0: 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64 65  So we have to de
2bd0: 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73 20  fine the macros 
2be0: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61 79  in different way
2bf0: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  s depending on t
2c00: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e 0a  he.** compiler..
2c10: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f  */.#if defined(_
2c20: 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29  _PTRDIFF_TYPE__)
2c30: 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20 73    /* This case s
2c40: 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20 47  hould work for G
2c50: 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53  CC */.# define S
2c60: 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52  QLITE_INT_TO_PTR
2c70: 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f 5f  (X)  ((void*)(__
2c80: 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28  PTRDIFF_TYPE__)(
2c90: 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  X)).# define SQL
2ca0: 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58  ITE_PTR_TO_INT(X
2cb0: 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52 44  )  ((int)(__PTRD
2cc0: 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29 0a  IFF_TYPE__)(X)).
2cd0: 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 5f  #elif !defined(_
2ce0: 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20 2f  _GNUC__)       /
2cf0: 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d 70  * Works for comp
2d00: 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61 6e  ilers other than
2d10: 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69 6e   LLVM */.# defin
2d20: 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f  e SQLITE_INT_TO_
2d30: 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29  PTR(X)  ((void*)
2d40: 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 0a  &((char*)0)[X]).
2d50: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2d60: 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28  PTR_TO_INT(X)  (
2d70: 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58 29  (int)(((char*)X)
2d80: 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c 69  -(char*)0)).#eli
2d90: 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f 53  f defined(HAVE_S
2da0: 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55 73  TDINT_H)   /* Us
2db0: 65 20 74 68 69 73 20 63 61 73 65 20 69 66 20 77  e this case if w
2dc0: 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 61 64  e have ANSI head
2dd0: 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20  ers */.# define 
2de0: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54  SQLITE_INT_TO_PT
2df0: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 69  R(X)  ((void*)(i
2e00: 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20 64  ntptr_t)(X)).# d
2e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52  efine SQLITE_PTR
2e20: 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e  _TO_INT(X)  ((in
2e30: 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29  t)(intptr_t)(X))
2e40: 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 20 20  .#else          
2e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e60: 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20 77  /* Generates a w
2e70: 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74 20  arning - but it 
2e80: 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f 0a  always works */.
2e90: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2ea0: 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20 28  INT_TO_PTR(X)  (
2eb0: 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64 65  (void*)(X)).# de
2ec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f  fine SQLITE_PTR_
2ed0: 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74  TO_INT(X)  ((int
2ee0: 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a  )(X)).#endif../*
2ef0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 54  .** The SQLITE_T
2f00: 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f 20  HREADSAFE macro 
2f10: 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 64 20  must be defined 
2f20: 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a 2a  as 0, 1, or 2..*
2f30: 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78 65  * 0 means mutexe
2f40: 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74 6c  s are permanentl
2f50: 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74 68  y disable and th
2f60: 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65 76  e library is nev
2f70: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 65  er.** threadsafe
2f80: 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20 6c  .  1 means the l
2f90: 69 62 72 61 72 79 20 69 73 20 73 65 72 69 61 6c  ibrary is serial
2fa0: 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 74 68  ized which is th
2fb0: 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65 76  e highest.** lev
2fc0: 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66 65  el of threadsafe
2fd0: 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68 65  ty.  2 means the
2fe0: 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c 74 69   libary is multi
2ff0: 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74 69  threaded - multi
3000: 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20 63  ple.** threads c
3010: 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61 73  an use SQLite as
3020: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
3030: 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20 75  threads try to u
3040: 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  se the same.** d
3050: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3060: 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  on at the same t
3070: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65 72  ime..**.** Older
3080: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
3090: 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74 69  ite used an opti
30a0: 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45 20  onal THREADSAFE 
30b0: 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75 70  macro..** We sup
30c0: 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c 65  port that for le
30d0: 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64 65  gacy..*/.#if !de
30e0: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48 52  fined(SQLITE_THR
30f0: 45 41 44 53 41 46 45 29 0a 23 20 69 66 20 64 65  EADSAFE).# if de
3100: 66 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45  fined(THREADSAFE
3110: 29 0a 23 20 20 20 64 65 66 69 6e 65 20 53 51 4c  ).#   define SQL
3120: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 54  ITE_THREADSAFE T
3130: 48 52 45 41 44 53 41 46 45 0a 23 20 65 6c 73 65  HREADSAFE.# else
3140: 0a 23 20 20 20 64 65 66 69 6e 65 20 53 51 4c 49  .#   define SQLI
3150: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 31 20  TE_THREADSAFE 1 
3160: 2f 2a 20 49 4d 50 3a 20 52 2d 30 37 32 37 32 2d  /* IMP: R-07272-
3170: 32 32 33 30 39 20 2a 2f 0a 23 20 65 6e 64 69 66  22309 */.# endif
3180: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 50  .#endif../*.** P
3190: 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
31a0: 74 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  te is on by defa
31b0: 75 6c 74 2e 20 20 42 75 74 20 63 61 6e 20 62 65  ult.  But can be
31c0: 20 74 75 72 6e 65 64 20 6f 66 66 20 75 73 69 6e   turned off usin
31d0: 67 0a 2a 2a 20 74 68 65 20 2d 44 53 51 4c 49 54  g.** the -DSQLIT
31e0: 45 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  E_POWERSAFE_OVER
31f0: 57 52 49 54 45 3d 30 20 63 6f 6d 6d 61 6e 64 2d  WRITE=0 command-
3200: 6c 69 6e 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2f 0a  line option..*/.
3210: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50  #ifndef SQLITE_P
3220: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
3230: 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  TE.# define SQLI
3240: 54 45 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TE_POWERSAFE_OVE
3250: 52 57 52 49 54 45 20 31 0a 23 65 6e 64 69 66 0a  RWRITE 1.#endif.
3260: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ./*.** The SQLIT
3270: 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
3280: 54 55 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 62  TUS macro must b
3290: 65 20 64 65 66 69 6e 65 64 20 61 73 20 65 69 74  e defined as eit
32a0: 68 65 72 20 30 20 6f 72 20 31 2e 0a 2a 2a 20 49  her 0 or 1..** I
32b0: 74 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  t determines whe
32c0: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
32d0: 66 65 61 74 75 72 65 73 20 72 65 6c 61 74 65 64  features related
32e0: 20 74 6f 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   to .** SQLITE_C
32f0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
3300: 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 62 79  are available by
3310: 20 64 65 66 61 75 6c 74 20 6f 72 20 6e 6f 74 2e   default or not.
3320: 20 54 68 69 73 20 76 61 6c 75 65 20 63 61 6e 0a   This value can.
3330: 2a 2a 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  ** be overridden
3340: 20 61 74 20 72 75 6e 74 69 6d 65 20 75 73 69 6e   at runtime usin
3350: 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
3360: 6e 66 69 67 28 29 20 41 50 49 2e 0a 2a 2f 0a 23  nfig() API..*/.#
3370: 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49  if !defined(SQLI
3380: 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
3390: 41 54 55 53 29 0a 23 20 64 65 66 69 6e 65 20 53  ATUS).# define S
33a0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
33b0: 4d 53 54 41 54 55 53 20 31 0a 23 65 6e 64 69 66  MSTATUS 1.#endif
33c0: 0a 0a 2f 2a 0a 2a 2a 20 45 78 61 63 74 6c 79 20  ../*.** Exactly 
33d0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
33e0: 77 69 6e 67 20 6d 61 63 72 6f 73 20 6d 75 73 74  wing macros must
33f0: 20 62 65 20 64 65 66 69 6e 65 64 20 69 6e 20 6f   be defined in o
3400: 72 64 65 72 20 74 6f 0a 2a 2a 20 73 70 65 63 69  rder to.** speci
3410: 66 79 20 77 68 69 63 68 20 6d 65 6d 6f 72 79 20  fy which memory 
3420: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
3430: 73 74 65 6d 20 74 6f 20 75 73 65 2e 0a 2a 2a 0a  stem to use..**.
3440: 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 53 59  **     SQLITE_SY
3450: 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  STEM_MALLOC     
3460: 20 20 20 20 20 2f 2f 20 55 73 65 20 6e 6f 72 6d       // Use norm
3470: 61 6c 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  al system malloc
3480: 28 29 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ().**     SQLITE
3490: 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 20 20 20  _WIN32_MALLOC   
34a0: 20 20 20 20 20 20 20 20 2f 2f 20 55 73 65 20 57          // Use W
34b0: 69 6e 33 32 20 6e 61 74 69 76 65 20 68 65 61 70  in32 native heap
34c0: 20 41 50 49 0a 2a 2a 20 20 20 20 20 53 51 4c 49   API.**     SQLI
34d0: 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 20 20  TE_ZERO_MALLOC  
34e0: 20 20 20 20 20 20 20 20 20 20 2f 2f 20 55 73 65            // Use
34f0: 20 61 20 73 74 75 62 20 61 6c 6c 6f 63 61 74 6f   a stub allocato
3500: 72 20 74 68 61 74 20 61 6c 77 61 79 73 20 66 61  r that always fa
3510: 69 6c 73 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ils.**     SQLIT
3520: 45 5f 4d 45 4d 44 45 42 55 47 20 20 20 20 20 20  E_MEMDEBUG      
3530: 20 20 20 20 20 20 20 20 20 2f 2f 20 44 65 62 75           // Debu
3540: 67 67 69 6e 67 20 76 65 72 73 69 6f 6e 20 6f 66  gging version of
3550: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
3560: 0a 2a 2a 0a 2a 2a 20 4f 6e 20 57 69 6e 64 6f 77  .**.** On Window
3570: 73 2c 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  s, if the SQLITE
3580: 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5f 56 41  _WIN32_MALLOC_VA
3590: 4c 49 44 41 54 45 20 6d 61 63 72 6f 20 69 73 20  LIDATE macro is 
35a0: 64 65 66 69 6e 65 64 20 61 6e 64 20 74 68 65 0a  defined and the.
35b0: 2a 2a 20 61 73 73 65 72 74 28 29 20 6d 61 63 72  ** assert() macr
35c0: 6f 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 65 61  o is enabled, ea
35d0: 63 68 20 63 61 6c 6c 20 69 6e 74 6f 20 74 68 65  ch call into the
35e0: 20 57 69 6e 33 32 20 6e 61 74 69 76 65 20 68 65   Win32 native he
35f0: 61 70 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20  ap subsystem.** 
3600: 77 69 6c 6c 20 63 61 75 73 65 20 48 65 61 70 56  will cause HeapV
3610: 61 6c 69 64 61 74 65 20 74 6f 20 62 65 20 63 61  alidate to be ca
3620: 6c 6c 65 64 2e 20 20 49 66 20 68 65 61 70 20 76  lled.  If heap v
3630: 61 6c 69 64 61 74 69 6f 6e 20 73 68 6f 75 6c 64  alidation should
3640: 20 66 61 69 6c 2c 20 61 6e 0a 2a 2a 20 61 73 73   fail, an.** ass
3650: 65 72 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 74  ertion will be t
3660: 72 69 67 67 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  riggered..**.** 
3670: 28 48 69 73 74 6f 72 69 63 61 6c 20 6e 6f 74 65  (Historical note
3680: 3a 20 20 54 68 65 72 65 20 75 73 65 64 20 74 6f  :  There used to
3690: 20 62 65 20 73 65 76 65 72 61 6c 20 6f 74 68 65   be several othe
36a0: 72 20 6f 70 74 69 6f 6e 73 2c 20 62 75 74 20 77  r options, but w
36b0: 65 27 76 65 0a 2a 2a 20 70 61 72 65 64 20 69 74  e've.** pared it
36c0: 20 64 6f 77 6e 20 74 6f 20 6a 75 73 74 20 74 68   down to just th
36d0: 65 73 65 20 74 68 72 65 65 2e 29 0a 2a 2a 0a 2a  ese three.).**.*
36e0: 2a 20 49 66 20 6e 6f 6e 65 20 6f 66 20 74 68 65  * If none of the
36f0: 20 61 62 6f 76 65 20 61 72 65 20 64 65 66 69 6e   above are defin
3700: 65 64 2c 20 74 68 65 6e 20 73 65 74 20 53 51 4c  ed, then set SQL
3710: 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f  ITE_SYSTEM_MALLO
3720: 43 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61  C as.** the defa
3730: 75 6c 74 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69  ult..*/.#if defi
3740: 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45  ned(SQLITE_SYSTE
3750: 4d 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20  M_MALLOC) \.  + 
3760: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 57  defined(SQLITE_W
3770: 49 4e 33 32 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20  IN32_MALLOC) \. 
3780: 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54   + defined(SQLIT
3790: 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 29 20 5c  E_ZERO_MALLOC) \
37a0: 0a 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c  .  + defined(SQL
37b0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3e 31 0a  ITE_MEMDEBUG)>1.
37c0: 23 20 65 72 72 6f 72 20 22 54 77 6f 20 6f 72 20  # error "Two or 
37d0: 6d 6f 72 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c  more of the foll
37e0: 6f 77 69 6e 67 20 63 6f 6d 70 69 6c 65 2d 74 69  owing compile-ti
37f0: 6d 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  me configuration
3800: 20 6f 70 74 69 6f 6e 73 5c 0a 20 61 72 65 20 64   options\. are d
3810: 65 66 69 6e 65 64 20 62 75 74 20 61 74 20 6d 6f  efined but at mo
3820: 73 74 20 6f 6e 65 20 69 73 20 61 6c 6c 6f 77 65  st one is allowe
3830: 64 3a 5c 0a 20 53 51 4c 49 54 45 5f 53 59 53 54  d:\. SQLITE_SYST
3840: 45 4d 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54  EM_MALLOC, SQLIT
3850: 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 2c 20  E_WIN32_MALLOC, 
3860: 53 51 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 2c  SQLITE_MEMDEBUG,
3870: 5c 0a 20 53 51 4c 49 54 45 5f 5a 45 52 4f 5f 4d  \. SQLITE_ZERO_M
3880: 41 4c 4c 4f 43 22 0a 23 65 6e 64 69 66 0a 23 69  ALLOC".#endif.#i
3890: 66 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45  f defined(SQLITE
38a0: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 29 20  _SYSTEM_MALLOC) 
38b0: 5c 0a 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51  \.  + defined(SQ
38c0: 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
38d0: 43 29 20 5c 0a 20 20 2b 20 64 65 66 69 6e 65 64  C) \.  + defined
38e0: 28 53 51 4c 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c  (SQLITE_ZERO_MAL
38f0: 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66 69 6e  LOC) \.  + defin
3900: 65 64 28 53 51 4c 49 54 45 5f 4d 45 4d 44 45 42  ed(SQLITE_MEMDEB
3910: 55 47 29 3d 3d 30 0a 23 20 64 65 66 69 6e 65 20  UG)==0.# define 
3920: 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41  SQLITE_SYSTEM_MA
3930: 4c 4c 4f 43 20 31 0a 23 65 6e 64 69 66 0a 0a 2f  LLOC 1.#endif../
3940: 2a 0a 2a 2a 20 49 66 20 53 51 4c 49 54 45 5f 4d  *.** If SQLITE_M
3950: 41 4c 4c 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49 54  ALLOC_SOFT_LIMIT
3960: 20 69 73 20 6e 6f 74 20 7a 65 72 6f 2c 20 74 68   is not zero, th
3970: 65 6e 20 74 72 79 20 74 6f 20 6b 65 65 70 20 74  en try to keep t
3980: 68 65 0a 2a 2a 20 73 69 7a 65 73 20 6f 66 20 6d  he.** sizes of m
3990: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
39a0: 73 20 62 65 6c 6f 77 20 74 68 69 73 20 76 61 6c  s below this val
39b0: 75 65 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c  ue where possibl
39c0: 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e  e..*/.#if !defin
39d0: 65 64 28 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43  ed(SQLITE_MALLOC
39e0: 5f 53 4f 46 54 5f 4c 49 4d 49 54 29 0a 23 20 64  _SOFT_LIMIT).# d
39f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 4c  efine SQLITE_MAL
3a00: 4c 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 20 31  LOC_SOFT_LIMIT 1
3a10: 30 32 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  024.#endif../*.*
3a20: 2a 20 57 65 20 6e 65 65 64 20 74 6f 20 64 65 66  * We need to def
3a30: 69 6e 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43  ine _XOPEN_SOURC
3a40: 45 20 61 73 20 66 6f 6c 6c 6f 77 73 20 69 6e 20  E as follows in 
3a50: 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 0a  order to enable.
3a60: 2a 2a 20 72 65 63 75 72 73 69 76 65 20 6d 75 74  ** recursive mut
3a70: 65 78 65 73 20 6f 6e 20 6d 6f 73 74 20 55 6e 69  exes on most Uni
3a80: 78 20 73 79 73 74 65 6d 73 2e 20 20 42 75 74 20  x systems.  But 
3a90: 4d 61 63 20 4f 53 20 58 20 69 73 20 64 69 66 66  Mac OS X is diff
3aa0: 65 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 5f 58  erent..** The _X
3ab0: 4f 50 45 4e 5f 53 4f 55 52 43 45 20 64 65 66 69  OPEN_SOURCE defi
3ac0: 6e 65 20 63 61 75 73 65 73 20 70 72 6f 62 6c 65  ne causes proble
3ad0: 6d 73 20 66 6f 72 20 4d 61 63 20 4f 53 20 58 20  ms for Mac OS X 
3ae0: 77 65 20 61 72 65 20 74 6f 6c 64 2c 0a 2a 2a 20  we are told,.** 
3af0: 73 6f 20 69 74 20 69 73 20 6f 6d 69 74 74 65 64  so it is omitted
3b00: 20 74 68 65 72 65 2e 20 20 53 65 65 20 74 69 63   there.  See tic
3b10: 6b 65 74 20 23 32 36 37 33 2e 0a 2a 2a 0a 2a 2a  ket #2673..**.**
3b20: 20 4c 61 74 65 72 20 77 65 20 6c 65 61 72 6e 20   Later we learn 
3b30: 74 68 61 74 20 5f 58 4f 50 45 4e 5f 53 4f 55 52  that _XOPEN_SOUR
3b40: 43 45 20 69 73 20 70 6f 6f 72 6c 79 20 6f 72 20  CE is poorly or 
3b50: 69 6e 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 69  incorrectly.** i
3b60: 6d 70 6c 65 6d 65 6e 74 65 64 20 6f 6e 20 73 6f  mplemented on so
3b70: 6d 65 20 73 79 73 74 65 6d 73 2e 20 20 53 6f 20  me systems.  So 
3b80: 77 65 20 61 76 6f 69 64 20 64 65 66 69 6e 69 6e  we avoid definin
3b90: 67 20 69 74 20 61 74 20 61 6c 6c 0a 2a 2a 20 69  g it at all.** i
3ba0: 66 20 69 74 20 69 73 20 61 6c 72 65 61 64 79 20  f it is already 
3bb0: 64 65 66 69 6e 65 64 20 6f 72 20 69 66 20 69 74  defined or if it
3bc0: 20 69 73 20 75 6e 6e 65 65 64 65 64 20 62 65 63   is unneeded bec
3bd0: 61 75 73 65 20 77 65 20 61 72 65 0a 2a 2a 20 6e  ause we are.** n
3be0: 6f 74 20 64 6f 69 6e 67 20 61 20 74 68 72 65 61  ot doing a threa
3bf0: 64 73 61 66 65 20 62 75 69 6c 64 2e 20 20 54 69  dsafe build.  Ti
3c00: 63 6b 65 74 20 23 32 36 38 31 2e 0a 2a 2a 0a 2a  cket #2681..**.*
3c10: 2a 20 53 65 65 20 61 6c 73 6f 20 74 69 63 6b 65  * See also ticke
3c20: 74 20 23 32 37 34 31 2e 0a 2a 2f 0a 23 69 66 20  t #2741..*/.#if 
3c30: 21 64 65 66 69 6e 65 64 28 5f 58 4f 50 45 4e 5f  !defined(_XOPEN_
3c40: 53 4f 55 52 43 45 29 20 26 26 20 21 64 65 66 69  SOURCE) && !defi
3c50: 6e 65 64 28 5f 5f 44 41 52 57 49 4e 5f 5f 29 20  ned(__DARWIN__) 
3c60: 5c 0a 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f  \. && !defined(_
3c70: 5f 41 50 50 4c 45 5f 5f 29 20 26 26 20 53 51 4c  _APPLE__) && SQL
3c80: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 0a 23  ITE_THREADSAFE.#
3c90: 20 20 64 65 66 69 6e 65 20 5f 58 4f 50 45 4e 5f    define _XOPEN_
3ca0: 53 4f 55 52 43 45 20 35 30 30 20 20 2f 2a 20 4e  SOURCE 500  /* N
3cb0: 65 65 64 65 64 20 74 6f 20 65 6e 61 62 6c 65 20  eeded to enable 
3cc0: 70 74 68 72 65 61 64 20 72 65 63 75 72 73 69 76  pthread recursiv
3cd0: 65 20 6d 75 74 65 78 65 73 20 2a 2f 0a 23 65 6e  e mutexes */.#en
3ce0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 54  dif../*.** The T
3cf0: 43 4c 20 68 65 61 64 65 72 73 20 61 72 65 20 6f  CL headers are o
3d00: 6e 6c 79 20 6e 65 65 64 65 64 20 77 68 65 6e 20  nly needed when 
3d10: 63 6f 6d 70 69 6c 69 6e 67 20 74 68 65 20 54 43  compiling the TC
3d20: 4c 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 23  L bindings..*/.#
3d30: 69 66 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54  if defined(SQLIT
3d40: 45 5f 54 43 4c 29 20 7c 7c 20 64 65 66 69 6e 65  E_TCL) || define
3d50: 64 28 54 43 4c 53 48 29 0a 23 20 69 6e 63 6c 75  d(TCLSH).# inclu
3d60: 64 65 20 3c 74 63 6c 2e 68 3e 0a 23 65 6e 64 69  de <tcl.h>.#endi
3d70: 66 0a 0a 2f 2a 0a 2a 2a 20 4e 44 45 42 55 47 20  f../*.** NDEBUG 
3d80: 61 6e 64 20 53 51 4c 49 54 45 5f 44 45 42 55 47  and SQLITE_DEBUG
3d90: 20 61 72 65 20 6f 70 70 6f 73 69 74 65 73 2e 20   are opposites. 
3da0: 20 49 74 20 73 68 6f 75 6c 64 20 61 6c 77 61 79   It should alway
3db0: 73 20 62 65 20 74 72 75 65 20 74 68 61 74 0a 2a  s be true that.*
3dc0: 2a 20 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47  * defined(NDEBUG
3dd0: 29 3d 3d 21 64 65 66 69 6e 65 64 28 53 51 4c 49  )==!defined(SQLI
3de0: 54 45 5f 44 45 42 55 47 29 2e 20 20 49 66 20 74  TE_DEBUG).  If t
3df0: 68 69 73 20 69 73 20 6e 6f 74 20 63 75 72 72 65  his is not curre
3e00: 6e 74 6c 79 20 74 72 75 65 2c 0a 2a 2a 20 6d 61  ntly true,.** ma
3e10: 6b 65 20 69 74 20 74 72 75 65 20 62 79 20 64 65  ke it true by de
3e20: 66 69 6e 69 6e 67 20 6f 72 20 75 6e 64 65 66 69  fining or undefi
3e30: 6e 69 6e 67 20 4e 44 45 42 55 47 2e 0a 2a 2a 0a  ning NDEBUG..**.
3e40: 2a 2a 20 53 65 74 74 69 6e 67 20 4e 44 45 42 55  ** Setting NDEBU
3e50: 47 20 6d 61 6b 65 73 20 74 68 65 20 63 6f 64 65  G makes the code
3e60: 20 73 6d 61 6c 6c 65 72 20 61 6e 64 20 72 75 6e   smaller and run
3e70: 20 66 61 73 74 65 72 20 62 79 20 64 69 73 61 62   faster by disab
3e80: 6c 69 6e 67 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  ling the.** numb
3e90: 65 72 20 61 73 73 65 72 74 28 29 20 73 74 61 74  er assert() stat
3ea0: 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 63 6f  ements in the co
3eb0: 64 65 2e 20 20 53 6f 20 77 65 20 77 61 6e 74 20  de.  So we want 
3ec0: 74 68 65 20 64 65 66 61 75 6c 74 20 61 63 74 69  the default acti
3ed0: 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 66 6f 72 20  on.** to be for 
3ee0: 4e 44 45 42 55 47 20 74 6f 20 62 65 20 73 65 74  NDEBUG to be set
3ef0: 20 61 6e 64 20 4e 44 45 42 55 47 20 74 6f 20 62   and NDEBUG to b
3f00: 65 20 75 6e 64 65 66 69 6e 65 64 20 6f 6e 6c 79  e undefined only
3f10: 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47   if SQLITE_DEBUG
3f20: 0a 2a 2a 20 69 73 20 73 65 74 2e 20 20 54 68 75  .** is set.  Thu
3f30: 73 20 4e 44 45 42 55 47 20 62 65 63 6f 6d 65 73  s NDEBUG becomes
3f40: 20 61 6e 20 6f 70 74 2d 69 6e 20 72 61 74 68 65   an opt-in rathe
3f50: 72 20 74 68 61 6e 20 61 6e 20 6f 70 74 2d 6f 75  r than an opt-ou
3f60: 74 0a 2a 2a 20 66 65 61 74 75 72 65 2e 0a 2a 2f  t.** feature..*/
3f70: 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44  .#if !defined(ND
3f80: 45 42 55 47 29 20 26 26 20 21 64 65 66 69 6e 65  EBUG) && !define
3f90: 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29 20  d(SQLITE_DEBUG) 
3fa0: 0a 23 20 64 65 66 69 6e 65 20 4e 44 45 42 55 47  .# define NDEBUG
3fb0: 20 31 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65   1.#endif.#if de
3fc0: 66 69 6e 65 64 28 4e 44 45 42 55 47 29 20 26 26  fined(NDEBUG) &&
3fd0: 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f   defined(SQLITE_
3fe0: 44 45 42 55 47 29 0a 23 20 75 6e 64 65 66 20 4e  DEBUG).# undef N
3ff0: 44 45 42 55 47 0a 23 65 6e 64 69 66 0a 0a 2f 2a  DEBUG.#endif../*
4000: 0a 2a 2a 20 54 68 65 20 74 65 73 74 63 61 73 65  .** The testcase
4010: 28 29 20 6d 61 63 72 6f 20 69 73 20 75 73 65 64  () macro is used
4020: 20 74 6f 20 61 69 64 20 69 6e 20 63 6f 76 65 72   to aid in cover
4030: 61 67 65 20 74 65 73 74 69 6e 67 2e 20 20 57 68  age testing.  Wh
4040: 65 6e 20 0a 2a 2a 20 64 6f 69 6e 67 20 63 6f 76  en .** doing cov
4050: 65 72 61 67 65 20 74 65 73 74 69 6e 67 2c 20 74  erage testing, t
4060: 68 65 20 63 6f 6e 64 69 74 69 6f 6e 20 69 6e 73  he condition ins
4070: 69 64 65 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ide the argument
4080: 20 74 6f 0a 2a 2a 20 74 65 73 74 63 61 73 65 28   to.** testcase(
4090: 29 20 6d 75 73 74 20 62 65 20 65 76 61 6c 75 61  ) must be evalua
40a0: 74 65 64 20 62 6f 74 68 20 74 72 75 65 20 61 6e  ted both true an
40b0: 64 20 66 61 6c 73 65 20 69 6e 20 6f 72 64 65 72  d false in order
40c0: 20 74 6f 0a 2a 2a 20 67 65 74 20 66 75 6c 6c 20   to.** get full 
40d0: 62 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65 2e  branch coverage.
40e0: 20 20 54 68 65 20 74 65 73 74 63 61 73 65 28 29    The testcase()
40f0: 20 6d 61 63 72 6f 20 69 73 20 69 6e 73 65 72 74   macro is insert
4100: 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 65 6e  ed.** to help en
4110: 73 75 72 65 20 61 64 65 71 75 61 74 65 20 74 65  sure adequate te
4120: 73 74 20 63 6f 76 65 72 61 67 65 20 69 6e 20 70  st coverage in p
4130: 6c 61 63 65 73 20 77 68 65 72 65 20 73 69 6d 70  laces where simp
4140: 6c 65 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 2f  le.** condition/
4150: 64 65 63 69 73 69 6f 6e 20 63 6f 76 65 72 61 67  decision coverag
4160: 65 20 69 73 20 69 6e 61 64 65 71 75 61 74 65 2e  e is inadequate.
4170: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74    For example, t
4180: 65 73 74 63 61 73 65 28 29 0a 2a 2a 20 63 61 6e  estcase().** can
4190: 20 62 65 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   be used to make
41a0: 20 73 75 72 65 20 62 6f 75 6e 64 61 72 79 20 76   sure boundary v
41b0: 61 6c 75 65 73 20 61 72 65 20 74 65 73 74 65 64  alues are tested
41c0: 2e 20 20 46 6f 72 0a 2a 2a 20 62 69 74 6d 61 73  .  For.** bitmas
41d0: 6b 20 74 65 73 74 73 2c 20 74 65 73 74 63 61 73  k tests, testcas
41e0: 65 28 29 20 63 61 6e 20 62 65 20 75 73 65 64 20  e() can be used 
41f0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 65 61 63  to make sure eac
4200: 68 20 62 69 74 0a 2a 2a 20 69 73 20 73 69 67 6e  h bit.** is sign
4210: 69 66 69 63 61 6e 74 20 61 6e 64 20 75 73 65 64  ificant and used
4220: 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 2e 20   at least once. 
4230: 20 4f 6e 20 73 77 69 74 63 68 20 73 74 61 74 65   On switch state
4240: 6d 65 6e 74 73 0a 2a 2a 20 77 68 65 72 65 20 6d  ments.** where m
4250: 75 6c 74 69 70 6c 65 20 63 61 73 65 73 20 67 6f  ultiple cases go
4260: 20 74 6f 20 74 68 65 20 73 61 6d 65 20 62 6c 6f   to the same blo
4270: 63 6b 20 6f 66 20 63 6f 64 65 2c 20 74 65 73 74  ck of code, test
4280: 63 61 73 65 28 29 0a 2a 2a 20 63 61 6e 20 69 6e  case().** can in
4290: 73 75 72 65 20 74 68 61 74 20 61 6c 6c 20 63 61  sure that all ca
42a0: 73 65 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  ses are evaluate
42b0: 64 2e 0a 2a 2a 0a 2a 2f 0a 23 69 66 64 65 66 20  d..**.*/.#ifdef 
42c0: 53 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 45 5f  SQLITE_COVERAGE_
42d0: 54 45 53 54 0a 53 51 4c 49 54 45 5f 50 52 49 56  TEST.SQLITE_PRIV
42e0: 41 54 45 20 20 20 76 6f 69 64 20 73 71 6c 69 74  ATE   void sqlit
42f0: 65 33 43 6f 76 65 72 61 67 65 28 69 6e 74 29 3b  e3Coverage(int);
4300: 0a 23 20 64 65 66 69 6e 65 20 74 65 73 74 63 61  .# define testca
4310: 73 65 28 58 29 20 20 69 66 28 20 58 20 29 7b 20  se(X)  if( X ){ 
4320: 73 71 6c 69 74 65 33 43 6f 76 65 72 61 67 65 28  sqlite3Coverage(
4330: 5f 5f 4c 49 4e 45 5f 5f 29 3b 20 7d 0a 23 65 6c  __LINE__); }.#el
4340: 73 65 0a 23 20 64 65 66 69 6e 65 20 74 65 73 74  se.# define test
4350: 63 61 73 65 28 58 29 0a 23 65 6e 64 69 66 0a 0a  case(X).#endif..
4360: 2f 2a 0a 2a 2a 20 54 68 65 20 54 45 53 54 4f 4e  /*.** The TESTON
4370: 4c 59 20 6d 61 63 72 6f 20 69 73 20 75 73 65 64  LY macro is used
4380: 20 74 6f 20 65 6e 63 6c 6f 73 65 20 76 61 72 69   to enclose vari
4390: 61 62 6c 65 20 64 65 63 6c 61 72 61 74 69 6f 6e  able declaration
43a0: 73 20 6f 72 0a 2a 2a 20 6f 74 68 65 72 20 62 69  s or.** other bi
43b0: 74 73 20 6f 66 20 63 6f 64 65 20 74 68 61 74 20  ts of code that 
43c0: 61 72 65 20 6e 65 65 64 65 64 20 74 6f 20 73 75  are needed to su
43d0: 70 70 6f 72 74 20 74 68 65 20 61 72 67 75 6d 65  pport the argume
43e0: 6e 74 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 65  nts.** within te
43f0: 73 74 63 61 73 65 28 29 20 61 6e 64 20 61 73 73  stcase() and ass
4400: 65 72 74 28 29 20 6d 61 63 72 6f 73 2e 0a 2a 2f  ert() macros..*/
4410: 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44  .#if !defined(ND
4420: 45 42 55 47 29 20 7c 7c 20 64 65 66 69 6e 65 64  EBUG) || defined
4430: 28 53 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 45  (SQLITE_COVERAGE
4440: 5f 54 45 53 54 29 0a 23 20 64 65 66 69 6e 65 20  _TEST).# define 
4450: 54 45 53 54 4f 4e 4c 59 28 58 29 20 20 58 0a 23  TESTONLY(X)  X.#
4460: 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 54 45  else.# define TE
4470: 53 54 4f 4e 4c 59 28 58 29 0a 23 65 6e 64 69 66  STONLY(X).#endif
4480: 0a 0a 2f 2a 0a 2a 2a 20 53 6f 6d 65 74 69 6d 65  ../*.** Sometime
4490: 73 20 77 65 20 6e 65 65 64 20 61 20 73 6d 61 6c  s we need a smal
44a0: 6c 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 64 65  l amount of code
44b0: 20 73 75 63 68 20 61 73 20 61 20 76 61 72 69 61   such as a varia
44c0: 62 6c 65 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ble initializati
44d0: 6f 6e 0a 2a 2a 20 74 6f 20 73 65 74 75 70 20 66  on.** to setup f
44e0: 6f 72 20 61 20 6c 61 74 65 72 20 61 73 73 65 72  or a later asser
44f0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  t() statement.  
4500: 57 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74  We do not want t
4510: 68 69 73 20 63 6f 64 65 20 74 6f 0a 2a 2a 20 61  his code to.** a
4520: 70 70 65 61 72 20 77 68 65 6e 20 61 73 73 65 72  ppear when asser
4530: 74 28 29 20 69 73 20 64 69 73 61 62 6c 65 64 2e  t() is disabled.
4540: 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20    The following 
4550: 6d 61 63 72 6f 20 69 73 20 74 68 65 72 65 66 6f  macro is therefo
4560: 72 65 0a 2a 2a 20 75 73 65 64 20 74 6f 20 63 6f  re.** used to co
4570: 6e 74 61 69 6e 20 74 68 61 74 20 73 65 74 75 70  ntain that setup
4580: 20 63 6f 64 65 2e 20 20 54 68 65 20 22 56 56 41   code.  The "VVA
4590: 22 20 61 63 72 6f 6e 79 6d 20 73 74 61 6e 64 73  " acronym stands
45a0: 20 66 6f 72 0a 2a 2a 20 22 56 65 72 69 66 69 63   for.** "Verific
45b0: 61 74 69 6f 6e 2c 20 56 61 6c 69 64 61 74 69 6f  ation, Validatio
45c0: 6e 2c 20 61 6e 64 20 41 63 63 72 65 64 69 74 61  n, and Accredita
45d0: 74 69 6f 6e 22 2e 20 20 49 6e 20 6f 74 68 65 72  tion".  In other
45e0: 20 77 6f 72 64 73 2c 20 74 68 65 0a 2a 2a 20 63   words, the.** c
45f0: 6f 64 65 20 77 69 74 68 69 6e 20 56 56 41 5f 4f  ode within VVA_O
4600: 4e 4c 59 28 29 20 77 69 6c 6c 20 6f 6e 6c 79 20  NLY() will only 
4610: 72 75 6e 20 64 75 72 69 6e 67 20 76 65 72 69 66  run during verif
4620: 69 63 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 65  ication processe
4630: 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44  s..*/.#ifndef ND
4640: 45 42 55 47 0a 23 20 64 65 66 69 6e 65 20 56 56  EBUG.# define VV
4650: 41 5f 4f 4e 4c 59 28 58 29 20 20 58 0a 23 65 6c  A_ONLY(X)  X.#el
4660: 73 65 0a 23 20 64 65 66 69 6e 65 20 56 56 41 5f  se.# define VVA_
4670: 4f 4e 4c 59 28 58 29 0a 23 65 6e 64 69 66 0a 0a  ONLY(X).#endif..
4680: 2f 2a 0a 2a 2a 20 54 68 65 20 41 4c 57 41 59 53  /*.** The ALWAYS
4690: 20 61 6e 64 20 4e 45 56 45 52 20 6d 61 63 72 6f   and NEVER macro
46a0: 73 20 73 75 72 72 6f 75 6e 64 20 62 6f 6f 6c 65  s surround boole
46b0: 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 73 20 77  an expressions w
46c0: 68 69 63 68 20 0a 2a 2a 20 61 72 65 20 69 6e 74  hich .** are int
46d0: 65 6e 64 65 64 20 74 6f 20 61 6c 77 61 79 73 20  ended to always 
46e0: 62 65 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65  be true or false
46f0: 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
4700: 20 53 75 63 68 0a 2a 2a 20 65 78 70 72 65 73 73   Such.** express
4710: 69 6f 6e 73 20 63 6f 75 6c 64 20 62 65 20 6f 6d  ions could be om
4720: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 63  itted from the c
4730: 6f 64 65 20 63 6f 6d 70 6c 65 74 65 6c 79 2e 20  ode completely. 
4740: 20 42 75 74 20 74 68 65 79 0a 2a 2a 20 61 72 65   But they.** are
4750: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 61 20 66   included in a f
4760: 65 77 20 63 61 73 65 73 20 69 6e 20 6f 72 64 65  ew cases in orde
4770: 72 20 74 6f 20 65 6e 68 61 6e 63 65 20 74 68 65  r to enhance the
4780: 20 72 65 73 69 6c 69 65 6e 63 65 0a 2a 2a 20 6f   resilience.** o
4790: 66 20 53 51 4c 69 74 65 20 74 6f 20 75 6e 65 78  f SQLite to unex
47a0: 70 65 63 74 65 64 20 62 65 68 61 76 69 6f 72 20  pected behavior 
47b0: 2d 20 74 6f 20 6d 61 6b 65 20 74 68 65 20 63 6f  - to make the co
47c0: 64 65 20 22 73 65 6c 66 2d 68 65 61 6c 69 6e 67  de "self-healing
47d0: 22 0a 2a 2a 20 6f 72 20 22 64 75 63 74 69 6c 65  ".** or "ductile
47e0: 22 20 72 61 74 68 65 72 20 74 68 61 6e 20 62 65  " rather than be
47f0: 69 6e 67 20 22 62 72 69 74 74 6c 65 22 20 61 6e  ing "brittle" an
4800: 64 20 63 72 61 73 68 69 6e 67 20 61 74 20 74 68  d crashing at th
4810: 65 20 66 69 72 73 74 0a 2a 2a 20 68 69 6e 74 20  e first.** hint 
4820: 6f 66 20 75 6e 70 6c 61 6e 6e 65 64 20 62 65 68  of unplanned beh
4830: 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  avior..**.** In 
4840: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 41 4c 57  other words, ALW
4850: 41 59 53 20 61 6e 64 20 4e 45 56 45 52 20 61 72  AYS and NEVER ar
4860: 65 20 61 64 64 65 64 20 66 6f 72 20 64 65 66 65  e added for defe
4870: 6e 73 69 76 65 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  nsive code..**.*
4880: 2a 20 57 68 65 6e 20 64 6f 69 6e 67 20 63 6f 76  * When doing cov
4890: 65 72 61 67 65 20 74 65 73 74 69 6e 67 20 41 4c  erage testing AL
48a0: 57 41 59 53 20 61 6e 64 20 4e 45 56 45 52 20 61  WAYS and NEVER a
48b0: 72 65 20 68 61 72 64 2d 63 6f 64 65 64 20 74 6f  re hard-coded to
48c0: 0a 2a 2a 20 62 65 20 74 72 75 65 20 61 6e 64 20  .** be true and 
48d0: 66 61 6c 73 65 20 73 6f 20 74 68 61 74 20 74 68  false so that th
48e0: 65 20 75 6e 72 65 61 63 68 61 62 6c 65 20 63 6f  e unreachable co
48f0: 64 65 20 74 68 65 6e 20 73 70 65 63 69 66 79 20  de then specify 
4900: 77 69 6c 6c 0a 2a 2a 20 6e 6f 74 20 62 65 20 63  will.** not be c
4910: 6f 75 6e 74 65 64 20 61 73 20 75 6e 74 65 73 74  ounted as untest
4920: 65 64 20 63 6f 64 65 2e 0a 2a 2f 0a 23 69 66 20  ed code..*/.#if 
4930: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 43  defined(SQLITE_C
4940: 4f 56 45 52 41 47 45 5f 54 45 53 54 29 0a 23 20  OVERAGE_TEST).# 
4950: 64 65 66 69 6e 65 20 41 4c 57 41 59 53 28 58 29  define ALWAYS(X)
4960: 20 20 20 20 20 20 28 31 29 0a 23 20 64 65 66 69        (1).# defi
4970: 6e 65 20 4e 45 56 45 52 28 58 29 20 20 20 20 20  ne NEVER(X)     
4980: 20 20 28 30 29 0a 23 65 6c 69 66 20 21 64 65 66    (0).#elif !def
4990: 69 6e 65 64 28 4e 44 45 42 55 47 29 0a 23 20 64  ined(NDEBUG).# d
49a0: 65 66 69 6e 65 20 41 4c 57 41 59 53 28 58 29 20  efine ALWAYS(X) 
49b0: 20 20 20 20 20 28 28 58 29 3f 31 3a 28 61 73 73       ((X)?1:(ass
49c0: 65 72 74 28 30 29 2c 30 29 29 0a 23 20 64 65 66  ert(0),0)).# def
49d0: 69 6e 65 20 4e 45 56 45 52 28 58 29 20 20 20 20  ine NEVER(X)    
49e0: 20 20 20 28 28 58 29 3f 28 61 73 73 65 72 74 28     ((X)?(assert(
49f0: 30 29 2c 31 29 3a 30 29 0a 23 65 6c 73 65 0a 23  0),1):0).#else.#
4a00: 20 64 65 66 69 6e 65 20 41 4c 57 41 59 53 28 58   define ALWAYS(X
4a10: 29 20 20 20 20 20 20 28 58 29 0a 23 20 64 65 66  )      (X).# def
4a20: 69 6e 65 20 4e 45 56 45 52 28 58 29 20 20 20 20  ine NEVER(X)    
4a30: 20 20 20 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f     (X).#endif../
4a40: 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 72 75 65  *.** Return true
4a50: 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
4a60: 68 65 20 69 6e 70 75 74 20 69 73 20 61 20 69 6e  he input is a in
4a70: 74 65 67 65 72 20 74 68 61 74 20 69 73 20 74 6f  teger that is to
4a80: 6f 20 6c 61 72 67 65 0a 2a 2a 20 74 6f 20 66 69  o large.** to fi
4a90: 74 20 69 6e 20 33 32 2d 62 69 74 73 2e 20 20 54  t in 32-bits.  T
4aa0: 68 69 73 20 6d 61 63 72 6f 20 69 73 20 75 73 65  his macro is use
4ab0: 64 20 69 6e 73 69 64 65 20 6f 66 20 76 61 72 69  d inside of vari
4ac0: 6f 75 73 20 74 65 73 74 63 61 73 65 28 29 0a 2a  ous testcase().*
4ad0: 2a 20 6d 61 63 72 6f 73 20 74 6f 20 76 65 72 69  * macros to veri
4ae0: 66 79 20 74 68 61 74 20 77 65 20 68 61 76 65 20  fy that we have 
4af0: 74 65 73 74 65 64 20 53 51 4c 69 74 65 20 66 6f  tested SQLite fo
4b00: 72 20 6c 61 72 67 65 2d 66 69 6c 65 20 73 75 70  r large-file sup
4b10: 70 6f 72 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  port..*/.#define
4b20: 20 49 53 5f 42 49 47 5f 49 4e 54 28 58 29 20 20   IS_BIG_INT(X)  
4b30: 28 28 28 58 29 26 7e 28 69 36 34 29 30 78 66 66  (((X)&~(i64)0xff
4b40: 66 66 66 66 66 66 29 21 3d 30 29 0a 0a 2f 2a 0a  ffffff)!=0)../*.
4b50: 2a 2a 20 54 68 65 20 6d 61 63 72 6f 20 75 6e 6c  ** The macro unl
4b60: 69 6b 65 6c 79 28 29 20 69 73 20 61 20 68 69 6e  ikely() is a hin
4b70: 74 20 74 68 61 74 20 73 75 72 72 6f 75 6e 64 73  t that surrounds
4b80: 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 65 78   a boolean.** ex
4b90: 70 72 65 73 73 69 6f 6e 20 74 68 61 74 20 69 73  pression that is
4ba0: 20 75 73 75 61 6c 6c 79 20 66 61 6c 73 65 2e 20   usually false. 
4bb0: 20 4d 61 63 72 6f 20 6c 69 6b 65 6c 79 28 29 20   Macro likely() 
4bc0: 73 75 72 72 6f 75 6e 64 73 0a 2a 2a 20 61 20 62  surrounds.** a b
4bd0: 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73 73 69 6f  oolean expressio
4be0: 6e 20 74 68 61 74 20 69 73 20 75 73 75 61 6c 6c  n that is usuall
4bf0: 79 20 74 72 75 65 2e 20 20 47 43 43 20 69 73 20  y true.  GCC is 
4c00: 61 62 6c 65 20 74 6f 0a 2a 2a 20 75 73 65 20 74  able to.** use t
4c10: 68 65 73 65 20 68 69 6e 74 73 20 74 6f 20 67 65  hese hints to ge
4c20: 6e 65 72 61 74 65 20 62 65 74 74 65 72 20 63 6f  nerate better co
4c30: 64 65 2c 20 73 6f 6d 65 74 69 6d 65 73 2e 0a 2a  de, sometimes..*
4c40: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f  /.#if defined(__
4c50: 47 4e 55 43 5f 5f 29 20 26 26 20 30 0a 23 20 64  GNUC__) && 0.# d
4c60: 65 66 69 6e 65 20 6c 69 6b 65 6c 79 28 58 29 20  efine likely(X) 
4c70: 20 20 20 5f 5f 62 75 69 6c 74 69 6e 5f 65 78 70     __builtin_exp
4c80: 65 63 74 28 28 58 29 2c 31 29 0a 23 20 64 65 66  ect((X),1).# def
4c90: 69 6e 65 20 75 6e 6c 69 6b 65 6c 79 28 58 29 20  ine unlikely(X) 
4ca0: 20 5f 5f 62 75 69 6c 74 69 6e 5f 65 78 70 65 63   __builtin_expec
4cb0: 74 28 28 58 29 2c 30 29 0a 23 65 6c 73 65 0a 23  t((X),0).#else.#
4cc0: 20 64 65 66 69 6e 65 20 6c 69 6b 65 6c 79 28 58   define likely(X
4cd0: 29 20 20 20 20 21 21 28 58 29 0a 23 20 64 65 66  )    !!(X).# def
4ce0: 69 6e 65 20 75 6e 6c 69 6b 65 6c 79 28 58 29 20  ine unlikely(X) 
4cf0: 20 21 21 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f   !!(X).#endif../
4d00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49  ************** I
4d10: 6e 63 6c 75 64 65 20 73 71 6c 69 74 65 33 2e 68  nclude sqlite3.h
4d20: 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
4d30: 66 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a  f sqliteInt.h **
4d40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
4d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42  ************** B
4d60: 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65  egin file sqlite
4d70: 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3.h ************
4d80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
4da0: 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 6d  *.** 2001 Septem
4db0: 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65  ber 15.**.** The
4dc0: 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d   author disclaim
4dd0: 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74  s copyright to t
4de0: 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e  his source code.
4df0: 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a    In place of.**
4e00: 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c   a legal notice,
4e10: 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73   here is a bless
4e20: 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61  ing:.**.**    Ma
4e30: 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e  y you do good an
4e40: 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20  d not evil..**  
4e50: 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66    May you find f
4e60: 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79  orgiveness for y
4e70: 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67  ourself and forg
4e80: 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20  ive others..**  
4e90: 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20    May you share 
4ea0: 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61  freely, never ta
4eb0: 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79  king more than y
4ec0: 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a  ou give..**.****
4ed0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ee0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ef0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4f00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4f10: 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65  *****.** This he
4f20: 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e 65  ader file define
4f30: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
4f40: 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 20  that the SQLite 
4f50: 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 65  library.** prese
4f60: 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 72  nts to client pr
4f70: 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 2d  ograms.  If a C-
4f80: 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 74  function, struct
4f90: 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a  ure, datatype,.*
4fa0: 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 65  * or constant de
4fb0: 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  finition does no
4fc0: 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 73  t appear in this
4fd0: 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 69   file, then it i
4fe0: 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69  s.** not a publi
4ff0: 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c 69  shed API of SQLi
5000: 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 74  te, is subject t
5010: 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
5020: 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20  .** notice, and 
5030: 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 65  should not be re
5040: 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f 67  ferenced by prog
5050: 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 51  rams that use SQ
5060: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  Lite..**.** Some
5070: 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 69   of the definiti
5080: 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e 20  ons that are in 
5090: 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d 61  this file are ma
50a0: 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 65  rked as.** "expe
50b0: 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 65  rimental".  Expe
50c0: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
50d0: 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79  ces are normally
50e0: 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 73   new.** features
50f0: 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 20   recently added 
5100: 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 64  to SQLite.  We d
5110: 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 65  o not anticipate
5120: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65   changes.** to e
5130: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65  xperimental inte
5140: 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 72  rfaces but reser
5150: 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f 20  ve the right to 
5160: 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67  make minor chang
5170: 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 65  es.** if experie
5180: 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 6e  nce from use "in
5190: 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 65   the wild" sugge
51a0: 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 20  st such changes 
51b0: 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a  are prudent..**.
51c0: 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c 20  ** The official 
51d0: 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 64  C-language API d
51e0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
51f0: 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 76   SQLite is deriv
5200: 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65  ed.** from comme
5210: 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c 65  nts in this file
5220: 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  .  This file is 
5230: 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 76  the authoritativ
5240: 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68  e source.** on h
5250: 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ow SQLite interf
5260: 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 65  aces are suppose
5270: 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a   to operate..**.
5280: 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
5290: 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 63  his file under c
52a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e  onfiguration man
52b0: 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c 69  agement is "sqli
52c0: 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65  te.h.in"..** The
52d0: 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 20   makefile makes 
52e0: 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67  some minor chang
52f0: 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 20  es to this file 
5300: 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 69  (such as inserti
5310: 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 6f  ng.** the versio
5320: 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 68  n number) and ch
5330: 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 74  anges its name t
5340: 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 73  o "sqlite3.h" as
5350: 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 20  .** part of the 
5360: 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a 2a  build process..*
5370: 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 54  /.#ifndef _SQLIT
5380: 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53  E3_H_.#define _S
5390: 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75  QLITE3_H_.#inclu
53a0: 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20  de <stdarg.h>   
53b0: 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20    /* Needed for 
53c0: 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  the definition o
53d0: 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a  f va_list */../*
53e0: 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65  .** Make sure we
53f0: 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73   can call this s
5400: 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a  tuff from C++..*
5410: 2f 0a 23 69 66 20 30 0a 65 78 74 65 72 6e 20 22  /.#if 0.extern "
5420: 43 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a  C" {.#endif.../*
5430: 0a 2a 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c  .** Add the abil
5440: 69 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ity to override 
5450: 27 65 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e  'extern'.*/.#ifn
5460: 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52  def SQLITE_EXTER
5470: 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  N.# define SQLIT
5480: 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a  E_EXTERN extern.
5490: 23 65 6e 64 69 66 0a 0a 23 69 66 6e 64 65 66 20  #endif..#ifndef 
54a0: 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66  SQLITE_API.# def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23  ine SQLITE_API.#
54c0: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68  endif.../*.** Th
54d0: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
54e0: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
54f0: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
5500: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
5510: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
5520: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
5530: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
5540: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
5550: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
5560: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
5570: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
5580: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 20  hey are support 
5590: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
55a0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
55b0: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
55c0: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
55d0: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
55e0: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
55f0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
5600: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
5610: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
5620: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
5630: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
5640: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
5650: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
5660: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
5670: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
5680: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
5690: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
56a0: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
56b0: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
56c0: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
56d0: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
56e0: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
56f0: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
5700: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
5710: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
5720: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
5730: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
5740: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5750: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
5760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
5770: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
5780: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
5790: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
57a0: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
57b0: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
57c0: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
57d0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
57e0: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
57f0: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
5800: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
5810: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
5820: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
5830: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
5840: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5850: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
5860: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
5870: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
5880: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
5890: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
58a0: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
58b0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
58c0: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
58d0: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
58e0: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
58f0: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
5900: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
5910: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
5920: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
5930: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
5940: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
5950: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
5960: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
5970: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
5980: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
5990: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
59a0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
59b0: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
59c0: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
59d0: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
59e0: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
59f0: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
5a00: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
5a10: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
5a20: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
5a30: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
5a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
5a50: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
5a60: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
5a70: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
5a80: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
5a90: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
5aa0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
5ab0: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
5ac0: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
5ad0: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
5ae0: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
5af0: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
5b00: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
5b10: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
5b20: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
5b30: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
5b40: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
5b50: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
5b60: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
5b70: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
5b80: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
5b90: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
5ba0: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
5bb0: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
5bc0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
5bd0: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
5be0: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
5bf0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
5c00: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
5c10: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
5c20: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
5c30: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
5c40: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
5c50: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
5c60: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
5c70: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
5c80: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
5c90: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
5ca0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
5cb0: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
5cc0: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
5cd0: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
5ce0: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
5cf0: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
5d00: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
5d10: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
5d20: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
5d30: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
5d40: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
5d50: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
5d60: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
5d70: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
5d80: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
5d90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5da0: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
5db0: 22 33 2e 37 2e 31 37 22 0a 23 64 65 66 69 6e 65  "3.7.17".#define
5dc0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
5dd0: 4e 55 4d 42 45 52 20 33 30 30 37 30 31 37 0a 23  NUMBER 3007017.#
5de0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f  define SQLITE_SO
5df0: 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 32 30  URCE_ID      "20
5e00: 31 33 2d 30 35 2d 31 36 20 30 31 3a 30 32 3a 34  13-05-16 01:02:4
5e10: 35 20 39 66 66 66 66 33 64 30 35 32 32 36 62 62  5 9ffff3d05226bb
5e20: 64 30 31 61 30 37 34 35 64 64 30 61 35 31 31 37  d01a0745dd0a5117
5e30: 37 36 33 35 38 32 35 33 63 30 22 0a 0a 2f 2a 0a  76358253c0"../*.
5e40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
5e50: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
5e60: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
5e70: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
5e80: 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69  e3_version, sqli
5e90: 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a  te3_sourceid.**.
5ea0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
5eb0: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
5ec0: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
5ed0: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
5ee0: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
5ef0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
5f00: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
5f10: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
5f20: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
5f30: 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73  os.** but are as
5f40: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
5f50: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61  e library instea
5f60: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20  d of the header 
5f70: 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75  file.  ^(Cautiou
5f80: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
5f90: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
5fa0: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
5fb0: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
5fc0: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
5fd0: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
5fe0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
5ff0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
6000: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
6010: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
6020: 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65   and thus insure
6030: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
6040: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
6050: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
6060: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
6070: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
6080: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
6090: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
60a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
60b0: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
60c0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
60d0: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
60e0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
60f0: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
6100: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
6110: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
6120: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
6130: 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45  version(),SQLITE
6140: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a  _VERSION)==0 );.
6150: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
6160: 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
6170: 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  The sqlite3_vers
6180: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
6190: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74  stant contains t
61a0: 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49  he text of [SQLI
61b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d  TE_VERSION].** m
61c0: 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  acro.  ^The sqli
61d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
61e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
61f0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
6200: 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c  he.** to the sql
6210: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
6220: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
6230: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
6240: 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e  version().** fun
6250: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
6260: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c  d for use in DLL
6270: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72  s since DLL user
6280: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  s usually do not
6290: 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20   have.** direct 
62a0: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
62b0: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69   constants withi
62c0: 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65  n the DLL.  ^The
62d0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  .** sqlite3_libv
62e0: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20  ersion_number() 
62f0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
6300: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61   an integer equa
6310: 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  l to.** [SQLITE_
6320: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
6330: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
6340: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
6350: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
6360: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
6370: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
6380: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
6390: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
63a0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
63b0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
63c0: 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  or macro..**.** 
63d0: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
63e0: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  e_version()] and
63f0: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f   [sqlite_source_
6400: 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  id()]..*/.SQLITE
6410: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
6420: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
6430: 5d 20 3d 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ] = SQLITE_VERSI
6440: 4f 4e 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  ON;.SQLITE_API c
6450: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
6460: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f  e3_libversion(vo
6470: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
6480: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
6490: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69  te3_sourceid(voi
64a0: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
64b0: 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  nt sqlite3_libve
64c0: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69  rsion_number(voi
64d0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
64e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
64f0: 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f  brary Compilatio
6500: 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f  n Options Diagno
6510: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stics.**.** ^The
6520: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
6530: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75  option_used() fu
6540: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30  nction returns 0
6550: 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61   or 1 .** indica
6560: 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65  ting whether the
6570: 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f   specified optio
6580: 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74  n was defined at
6590: 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d   .** compile tim
65a0: 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  e.  ^The SQLITE_
65b0: 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f   prefix may be o
65c0: 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
65d0: 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20  .** option name 
65e0: 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65  passed to sqlite
65f0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
6600: 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20  used().  .**.** 
6610: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
6620: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
6630: 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73   function allows
6640: 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76   iterating.** ov
6650: 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f  er the list of o
6660: 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65  ptions that were
6670: 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70   defined at comp
6680: 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72  ile time by.** r
6690: 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74  eturning the N-t
66a0: 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f  h compile time o
66b0: 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e  ption string.  ^
66c0: 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  If N is out of r
66d0: 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ange,.** sqlite3
66e0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
66f0: 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  et() returns a N
6700: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
6710: 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70  he SQLITE_ .** p
6720: 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64  refix is omitted
6730: 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67   from any string
6740: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a  s returned by .*
6750: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
6760: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a  eoption_get()..*
6770: 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f  *.** ^Support fo
6780: 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63  r the diagnostic
6790: 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74   functions sqlit
67a0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
67b0: 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73  _used().** and s
67c0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
67d0: 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62  tion_get() may b
67e0: 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65  e omitted by spe
67f0: 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20  cifying the .** 
6800: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d  [SQLITE_OMIT_COM
6810: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
6820: 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70  ] option at comp
6830: 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile time..**.** 
6840: 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75  See also: SQL fu
6850: 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f  nctions [sqlite_
6860: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
6870: 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
6880: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  lite_compileopti
6890: 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68  on_get()] and th
68a0: 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f  e [compile_optio
68b0: 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23  ns pragma]..*/.#
68c0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
68d0: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e  IT_COMPILEOPTION
68e0: 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50  _DIAGS.SQLITE_AP
68f0: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
6900: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
6910: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70  (const char *zOp
6920: 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41  tName);.SQLITE_A
6930: 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
6940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
6950: 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b  tion_get(int N);
6960: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
6970: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
6980: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
6990: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
69a0: 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
69b0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
69c0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
69d0: 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f  ns zero if and o
69e0: 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65  nly if.** SQLite
69f0: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
6a00: 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65  th mutexing code
6a10: 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20   omitted due to 
6a20: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
6a30: 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69  HREADSAFE] compi
6a40: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62  le-time option b
6a50: 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a  eing set to 0..*
6a60: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20  *.** SQLite can 
6a70: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  be compiled with
6a80: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65   or without mute
6a90: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68  xes.  When.** th
6aa0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
6ab0: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65  SAFE] C preproce
6ac0: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20  ssor macro is 1 
6ad0: 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a  or 2, mutexes.**
6ae0: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64   are enabled and
6af0: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61   SQLite is threa
6b00: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65  dsafe.  When the
6b10: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
6b20: 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73  ADSAFE] macro is
6b30: 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65   0, .** the mute
6b40: 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e  xes are omitted.
6b50: 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75    Without the mu
6b60: 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74  texes, it is not
6b70: 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20   safe.** to use 
6b80: 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e  SQLite concurren
6b90: 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68  tly from more th
6ba0: 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a  an one thread..*
6bb0: 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75  *.** Enabling mu
6bc0: 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d  texes incurs a m
6bd0: 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72  easurable perfor
6be0: 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a  mance penalty..*
6bf0: 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 73  * So if speed is
6c00: 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72   of utmost impor
6c10: 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20  tance, it makes 
6c20: 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65  sense to disable
6c30: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e  .** the mutexes.
6c40: 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75    But for maximu
6c50: 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65  m safety, mutexe
6c60: 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62  s should be enab
6c70: 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  led..** ^The def
6c80: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73  ault behavior is
6c90: 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20   for mutexes to 
6ca0: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  be enabled..**.*
6cb0: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
6cc0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 20   can be used by 
6cd0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
6ce0: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
6cf0: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   the.** version 
6d00: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  of SQLite that i
6d10: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61  t is linking aga
6d20: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65  inst was compile
6d30: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65  d with.** the de
6d40: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66  sired setting of
6d50: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
6d60: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a  EADSAFE] macro..
6d70: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
6d80: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74  face only report
6d90: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  s on the compile
6da0: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74  -time mutex sett
6db0: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  ing.** of the [S
6dc0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
6dd0: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69  ] flag.  If SQLi
6de0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
6df0: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48  ith.** SQLITE_TH
6e00: 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32  READSAFE=1 or =2
6e10: 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72   then mutexes ar
6e20: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
6e30: 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20  ault but.** can 
6e40: 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74  be fully or part
6e50: 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75  ially disabled u
6e60: 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  sing a call to [
6e70: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
6e80: 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65  ].** with the ve
6e90: 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  rbs [SQLITE_CONF
6ea0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
6eb0: 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  , [SQLITE_CONFIG
6ec0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a  _MULTITHREAD],.*
6ed0: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  * or [SQLITE_CON
6ee0: 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 54  FIG_MUTEX].  ^(T
6ef0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
6f00: 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  of the.** sqlite
6f10: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
6f20: 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e  unction shows on
6f30: 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  ly the compile-t
6f40: 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a  ime setting of.*
6f50: 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79 2c  * thread safety,
6f60: 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d   not any run-tim
6f70: 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61  e changes to tha
6f80: 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62  t setting made b
6f90: 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  y.** sqlite3_con
6fa0: 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20  fig(). In other 
6fb0: 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75 72  words, the retur
6fc0: 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
6fd0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
6fe0: 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65  ).** is unchange
6ff0: 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71  d by calls to sq
7000: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29  lite3_config().)
7010: 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20  ^.**.** See the 
7020: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
7030: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
7040: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
7050: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51  formation..*/.SQ
7060: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
7070: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
7080: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
7090: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
70a0: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
70b0: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
70c0: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
70d0: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
70e0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
70f0: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
7100: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
7110: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
7120: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7130: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
7140: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
7150: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
7160: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
7170: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
7180: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
7190: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
71a0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
71b0: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
71c0: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
71d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
71e0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
71f0: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
7200: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
7210: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
7220: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
7230: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
7240: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
7250: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
7260: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
7270: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
7280: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
7290: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
72a0: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
72b0: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
72c0: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
72d0: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
72e0: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
72f0: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
7300: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
7310: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
7320: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
7330: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
7340: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
7350: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
7360: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
7370: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
7380: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
7390: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
73a0: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
73b0: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
73c0: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
73d0: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
73e0: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
73f0: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
7400: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
7410: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
7420: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
7430: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
7440: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
7450: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
7460: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
7470: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
7480: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
7490: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
74a0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
74b0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
74c0: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
74d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
74e0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
74f0: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
7500: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
7510: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
7520: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
7530: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
7540: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
7550: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
7560: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
7570: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
7580: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
7590: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
75a0: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
75b0: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
75c0: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
75d0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
75e0: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
75f0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
7600: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
7610: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
7620: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36  gned SQLITE_INT6
7630: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
7640: 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69  nt64;.#elif defi
7650: 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c  ned(_MSC_VER) ||
7660: 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41   defined(__BORLA
7670: 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66  NDC__).  typedef
7680: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 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 5f 5f 69 6e 74 36   unsigned __int6
76b0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  4 sqlite_uint64;
76c0: 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66  .#else.  typedef
76d0: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
76e0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
76f0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
7700: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
7710: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e  lite_uint64;.#en
7720: 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69  dif.typedef sqli
7730: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  te_int64 sqlite3
7740: 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20  _int64;.typedef 
7750: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71  sqlite_uint64 sq
7760: 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f  lite3_uint64;../
7770: 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e  *.** If compilin
7780: 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f  g for a processo
7790: 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f  r that lacks flo
77a0: 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70  ating point supp
77b0: 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75  ort,.** substitu
77c0: 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66  te integer for f
77d0: 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a  loating-point..*
77e0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
77f0: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f  OMIT_FLOATING_PO
7800: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75  INT.# define dou
7810: 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ble sqlite3_int6
7820: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  4.#endif../*.** 
7830: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e  CAPI3REF: Closin
7840: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  g A Database Con
7850: 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
7860: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
7870: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
7880: 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e  lose_v2() routin
7890: 65 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f  es are destructo
78a0: 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73  rs.** for the [s
78b0: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
78c0: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
78d0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
78e0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
78f0: 32 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  2() return SQLIT
7900: 45 5f 4f 4b 20 69 66 0a 2a 2a 20 74 68 65 20 5b  E_OK if.** the [
7910: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
7920: 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  is successfully 
7930: 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c  destroyed and al
7940: 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  l associated.** 
7950: 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65  resources are de
7960: 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  allocated..**.**
7970: 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
7980: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
7990: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
79a0: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
79b0: 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
79c0: 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  ts or unfinished
79d0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
79e0: 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c  objects then sql
79f0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20  ite3_close().** 
7a00: 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64  will leave the d
7a10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
7a20: 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75  on open and retu
7a30: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
7a40: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
7a50: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
7a60: 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e  alled with unfin
7a70: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 20  alized prepared 
7a80: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e  statements.** an
7a90: 64 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  d unfinished sql
7aa0: 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68  ite3_backups, th
7ab0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
7ac0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d  connection becom
7ad0: 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c  es.** an unusabl
7ae0: 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68  e "zombie" which
7af0: 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
7b00: 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  lly be deallocat
7b10: 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c  ed when the.** l
7b20: 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ast prepared sta
7b30: 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69  tement is finali
7b40: 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20  zed or the last 
7b50: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69  sqlite3_backup i
7b60: 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20  s.** finished.  
7b70: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  The sqlite3_clos
7b80: 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
7b90: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
7ba0: 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73   use with.** hos
7bb0: 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74  t languages that
7bc0: 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c   are garbage col
7bd0: 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72  lected, and wher
7be0: 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77  e the order in w
7bf0: 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74  hich.** destruct
7c00: 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69  ors are called i
7c10: 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a  s arbitrary..**.
7c20: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
7c30: 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f  should [sqlite3_
7c40: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
7c50: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72  ize] all [prepar
7c60: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a  ed statements],.
7c70: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
7c80: 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20  _close | close] 
7c90: 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  all [BLOB handle
7ca0: 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  s], and .** [sql
7cb0: 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69  ite3_backup_fini
7cc0: 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c  sh | finish] all
7cd0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
7ce0: 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69  ] objects associ
7cf0: 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
7d00: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
7d10: 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d  t prior to attem
7d20: 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74  pting to close t
7d30: 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a  he object.  ^If.
7d40: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ** sqlite3_close
7d50: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
7d60: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
7d70: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
7d80: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
7d90: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
7da0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
7db0: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
7dc0: 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  and/or.** [sqlit
7dd0: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
7de0: 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ts then it retur
7df0: 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 62 75 74  ns SQLITE_OK but
7e00: 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f   the deallocatio
7e10: 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65  n.** of resource
7e20: 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e  s is deferred un
7e30: 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  til all [prepare
7e40: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
7e50: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a  BLOB handles],.*
7e60: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  * and [sqlite3_b
7e70: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61  ackup] objects a
7e80: 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65  re also destroye
7e90: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
7ea0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
7eb0: 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68   is destroyed wh
7ec0: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ile a transactio
7ed0: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68  n is open,.** th
7ee0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  e transaction is
7ef0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
7f00: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
7f10: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65  * The C paramete
7f20: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
7f30: 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c  ose(C)] and [sql
7f40: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29  ite3_close_v2(C)
7f50: 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
7f60: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f  her a NULL.** po
7f70: 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c  inter or an [sql
7f80: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69  ite3] object poi
7f90: 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  nter obtained.**
7fa0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f   from [sqlite3_o
7fb0: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
7fc0: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  _open16()], or.*
7fd0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
7fe0: 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70  v2()], and not p
7ff0: 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64  reviously closed
8000: 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  ..** ^Calling sq
8010: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72  lite3_close() or
8020: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
8030: 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  2() with a NULL 
8040: 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d  pointer.** argum
8050: 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ent is a harmles
8060: 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49  s no-op..*/.SQLI
8070: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
8080: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
8090: 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
80a0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
80b0: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
80c0: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
80d0: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
80e0: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
80f0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
8100: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
8110: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
8120: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
8130: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
8140: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
8150: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
8160: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
8170: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
8180: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
8190: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
81a0: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
81b0: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
81c0: 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ce.**.** The sql
81d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
81e0: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
81f0: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
8200: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
8210: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
8220: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
8230: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
8240: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
8250: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
8260: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
8270: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
8280: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
8290: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
82a0: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
82b0: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
82c0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
82d0: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
82e0: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
82f0: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
8300: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
8310: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
8320: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
8330: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
8340: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
8350: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
8360: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
8370: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
8380: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
8390: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
83a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
83b0: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
83c0: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
83d0: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
83e0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
83f0: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
8400: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
8410: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
8420: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
8430: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
8440: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
8450: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8460: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
8470: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
8480: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
8490: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
84a0: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
84b0: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
84c0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
84d0: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
84e0: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
84f0: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
8500: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
8510: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
8520: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
8530: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
8540: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
8550: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
8560: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
8570: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
8580: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
8590: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
85a0: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
85b0: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
85c0: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
85d0: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
85e0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
85f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
8600: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
8610: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
8620: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
8630: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
8640: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
8650: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
8660: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
8670: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
8680: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
8690: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
86a0: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
86b0: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
86c0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
86d0: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
86e0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
86f0: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
8700: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
8710: 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  r of.** of sqlit
8720: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
8730: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
8740: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
8750: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
8760: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
8770: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
8780: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
8790: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
87a0: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
87b0: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
87c0: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
87d0: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
87e0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
87f0: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
8800: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
8810: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8820: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
8830: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
8840: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
8850: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
8860: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
8870: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
8880: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
8890: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
88a0: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
88b0: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
88c0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
88d0: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
88e0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
88f0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
8900: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
8910: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
8920: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
8930: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
8940: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
8950: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
8960: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
8970: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
8980: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
8990: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
89a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
89b0: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
89c0: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
89d0: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
89e0: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
89f0: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
8a00: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
8a10: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
8a20: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
8a30: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
8a40: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
8a50: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
8a60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
8a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
8a80: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
8a90: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
8aa0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
8ab0: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
8ac0: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
8ad0: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
8ae0: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
8af0: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
8b00: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
8b10: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
8b20: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
8b30: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
8b40: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
8b50: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
8b60: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
8b70: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
8b80: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
8b90: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
8ba0: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
8bb0: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
8bc0: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
8bd0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
8be0: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
8bf0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
8c00: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
8c10: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
8c20: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
8c30: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
8c40: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e  lication must in
8c50: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
8c60: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
8c70: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
8c80: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
8c90: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
8ca0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
8cb0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
8cc0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
8cd0: 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73  t close [databas
8ce0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
8cf0: 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
8d00: 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d     the 1st param
8d10: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
8d20: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
8d30: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
8d40: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20  unning..** <li> 
8d50: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
8d60: 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20  must not modify 
8d70: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
8d80: 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e  t text passed in
8d90: 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32  to.**      the 2
8da0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
8db0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
8dc0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
8dd0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
8de0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ul>.*/.SQLI
8df0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
8e00: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
8e10: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
8e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8e30: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
8e40: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
8e50: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
8e60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8e70: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
8e80: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
8e90: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
8ea0: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
8eb0: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
8ec0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
8ed0: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
8ee0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
8ef0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8f00: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
8f10: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
8f20: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
8f30: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
8f40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8f50: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
8f60: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
8f70: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8f80: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  F: Result Codes.
8f90: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
8fa0: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f  ITE_OK {error co
8fb0: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73  de} {error codes
8fc0: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
8fd0: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65  result code} {re
8fe0: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
8ff0: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
9000: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
9010: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
9020: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
9030: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
9040: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
9050: 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72  icate success or
9060: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
9070: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
9080: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
9090: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
90a0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
90b0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
90c0: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
90d0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
90e0: 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  codes],.** [sqli
90f0: 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
9100: 6c 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f  lict()] [SQLITE_
9110: 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c  ROLLBACK | resul
9120: 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65  t codes]..*/.#de
9130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20  fine SQLITE_OK  
9140: 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
9150: 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c  Successful resul
9160: 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e  t */./* beginnin
9170: 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  g-of-error-codes
9180: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
9190: 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20  TE_ERROR        
91a0: 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72  1   /* SQL error
91b0: 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61   or missing data
91c0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
91d0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20  SQLITE_INTERNAL 
91e0: 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72      2   /* Inter
91f0: 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  nal logic error 
9200: 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65  in SQLite */.#de
9210: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d  fine SQLITE_PERM
9220: 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20           3   /* 
9230: 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f  Access permissio
9240: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
9250: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
9260: 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43          4   /* C
9270: 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
9280: 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f  requested an abo
9290: 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  rt */.#define SQ
92a0: 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20  LITE_BUSY       
92b0: 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74    5   /* The dat
92c0: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f  abase file is lo
92d0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
92e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20  SQLITE_LOCKED   
92f0: 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62      6   /* A tab
9300: 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  le in the databa
9310: 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  se is locked */.
9320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
9330: 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20  OMEM        7   
9340: 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61  /* A malloc() fa
9350: 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  iled */.#define 
9360: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
9370: 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d      8   /* Attem
9380: 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65  pt to write a re
9390: 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20  adonly database 
93a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
93b0: 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39  E_INTERRUPT    9
93c0: 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
93d0: 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71  terminated by sq
93e0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
93f0: 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )*/.#define SQLI
9400: 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31  TE_IOERR       1
9410: 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64  0   /* Some kind
9420: 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72   of disk I/O err
9430: 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23  or occurred */.#
9440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
9450: 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f  RRUPT     11   /
9460: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64  * The database d
9470: 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c  isk image is mal
9480: 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e  formed */.#defin
9490: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  e SQLITE_NOTFOUN
94a0: 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b  D    12   /* Unk
94b0: 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73  nown opcode in s
94c0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
94d0: 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  rol() */.#define
94e0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
94f0: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
9500: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
9510: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
9520: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
9530: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
9540: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
9550: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
9560: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
9570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
9580: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
9590: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
95a0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
95b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
95c0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
95d0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
95e0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
95f0: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
9600: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
9610: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
9620: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
9630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
9640: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
9650: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
9660: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
9670: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
9680: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
9690: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
96a0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
96b0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
96c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
96d0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
96e0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
96f0: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
9700: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
9710: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
9720: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
9730: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
9740: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
9750: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
9760: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
9770: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
9780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9790: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
97a0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
97b0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
97c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
97d0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
97e0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
97f0: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
9800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9810: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
9820: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
9830: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
9840: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
9850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
9860: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
9870: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
9880: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
9890: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
98a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
98b0: 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20  _NOTICE      27 
98c0: 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f    /* Notificatio
98d0: 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ns from sqlite3_
98e0: 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  log() */.#define
98f0: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20   SQLITE_WARNING 
9900: 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e      28   /* Warn
9910: 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  ings from sqlite
9920: 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69  3_log() */.#defi
9930: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
9940: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
9950: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
9960: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
9970: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
9980: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
9990: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
99a0: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
99b0: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
99c0: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
99d0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
99e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
99f0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
9a00: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
9a10: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
9a20: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
9a30: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
9a40: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
9a50: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
9a60: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
9a70: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
9a80: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
9a90: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
9aa0: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
9ab0: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
9ac0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
9ad0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
9ae0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
9af0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
9b00: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
9b10: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
9b20: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
9b30: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
9b40: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
9b50: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
9b60: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
9b70: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
9b80: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
9b90: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
9ba0: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
9bb0: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
9bc0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
9bd0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
9be0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
9bf0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
9c00: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
9c10: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
9c20: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
9c30: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
9c40: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
9c50: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
9c60: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
9c70: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
9c80: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
9c90: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
9ca0: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
9cb0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
9cc0: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
9cd0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
9ce0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
9cf0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
9d00: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
9d10: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
9d20: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
9d30: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
9d40: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
9d50: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
9d60: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
9d70: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
9d80: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
9d90: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
9da0: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
9db0: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
9dc0: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
9dd0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
9de0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
9df0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
9e00: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
9e10: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
9e20: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
9e30: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
9e40: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
9e50: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
9e60: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
9e70: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
9e80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9e90: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
9ea0: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
9eb0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
9ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
9ed0: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
9ee0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
9ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
9f00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9f10: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
9f20: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9f30: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
9f40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
9f50: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
9f60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
9f70: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
9f80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9f90: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
9fa0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9fb0: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
9fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
9fd0: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
9fe0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
9ff0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
a000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
a010: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
a020: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
a030: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
a040: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
a050: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
a060: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
a070: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
a080: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a090: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
a0a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a0b0: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
a0c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a0d0: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
a0e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a0f0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
a100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a110: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
a120: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a130: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
a140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a150: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
a160: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a170: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
a180: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a190: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
a1a0: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
a1b0: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
a1c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a1d0: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
a1e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a1f0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
a200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a210: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
a220: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a230: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
a240: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a250: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
a260: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a270: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
a280: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a290: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
a2a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a2b0: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
a2c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a2d0: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
a2e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a2f0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
a300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a310: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
a320: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a330: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
a340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a350: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
a360: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a370: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
a380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a390: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
a3a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a3b0: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
a3c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a3d0: 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20  R_DELETE_NOENT  
a3e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a3f0: 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65  R | (23<<8)).#de
a400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a410: 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  R_MMAP          
a420: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a430: 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65  R | (24<<8)).#de
a440: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
a450: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
a460: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
a470: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
a480: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
a490: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
a4a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
a4b0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
a4c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
a4d0: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
a4e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
a4f0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
a500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a510: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
a520: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a530: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
a540: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a550: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
a560: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
a570: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
a580: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
a590: 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42  ITE_CORRUPT_VTAB
a5a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
a5b0: 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31  ITE_CORRUPT | (1
a5c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
a5d0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45  LITE_READONLY_RE
a5e0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51  COVERY       (SQ
a5f0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
a600: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
a610: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
a620: 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28  CANTLOCK       (
a630: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
a640: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
a650: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
a660: 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  Y_ROLLBACK      
a670: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
a680: 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  Y | (3<<8)).#def
a690: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
a6a0: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
a6b0: 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54     (SQLITE_ABORT
a6c0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
a6d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
a6e0: 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20  AINT_CHECK      
a6f0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
a700: 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AINT | (1<<8)).#
a710: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
a720: 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48  NSTRAINT_COMMITH
a730: 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  OOK   (SQLITE_CO
a740: 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38  NSTRAINT | (2<<8
a750: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a760: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52  E_CONSTRAINT_FOR
a770: 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54  EIGNKEY   (SQLIT
a780: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
a790: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
a7a0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
a7b0: 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53  _FUNCTION     (S
a7c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
a7d0: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
a7e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
a7f0: 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20  AINT_NOTNULL    
a800: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
a810: 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23  AINT | (5<<8)).#
a820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
a830: 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59  NSTRAINT_PRIMARY
a840: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
a850: 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38  NSTRAINT | (6<<8
a860: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a870: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49  E_CONSTRAINT_TRI
a880: 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54  GGER      (SQLIT
a890: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
a8a0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
a8b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
a8c0: 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53  _UNIQUE       (S
a8d0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
a8e0: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
a8f0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
a900: 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20  AINT_VTAB       
a910: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
a920: 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23  AINT | (9<<8)).#
a930: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
a940: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c  TICE_RECOVER_WAL
a950: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f        (SQLITE_NO
a960: 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23  TICE | (1<<8)).#
a970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
a980: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c  TICE_RECOVER_ROL
a990: 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f  LBACK (SQLITE_NO
a9a0: 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 0a  TICE | (2<<8))..
a9b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a9c0: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
a9d0: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
a9e0: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
a9f0: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
aa00: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
aa10: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
aa20: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
aa30: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
aa40: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
aa50: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
aa60: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
aa70: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
aa80: 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ethod..*/.#defin
aa90: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
aaa0: 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30  ADONLY         0
aab0: 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b  x00000001  /* Ok
aac0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
aad0: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
aae0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
aaf0: 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30  ADWRITE        0
ab00: 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b  x00000002  /* Ok
ab10: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
ab20: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
ab30: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  e SQLITE_OPEN_CR
ab40: 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30  EATE           0
ab50: 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b  x00000004  /* Ok
ab60: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
ab70: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
ab80: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45  e SQLITE_OPEN_DE
ab90: 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30  LETEONCLOSE    0
aba0: 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46  x00000008  /* VF
abb0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
abc0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
abd0: 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30  CLUSIVE        0
abe0: 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46  x00000010  /* VF
abf0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
ac00: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55  e SQLITE_OPEN_AU
ac10: 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30  TOPROXY        0
ac20: 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46  x00000020  /* VF
ac30: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
ac40: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
ac50: 49 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  I              0
ac60: 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b  x00000040  /* Ok
ac70: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
ac80: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
ac90: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45  e SQLITE_OPEN_ME
aca0: 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20 20 30  MORY           0
acb0: 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b  x00000080  /* Ok
acc0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
acd0: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
ace0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
acf0: 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  IN_DB          0
ad00: 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46  x00000100  /* VF
ad10: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
ad20: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
ad30: 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  MP_DB          0
ad40: 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46  x00000200  /* VF
ad50: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
ad60: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52  e SQLITE_OPEN_TR
ad70: 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30  ANSIENT_DB     0
ad80: 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46  x00000400  /* VF
ad90: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
ada0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
adb0: 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  IN_JOURNAL     0
adc0: 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46  x00000800  /* VF
add0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
ade0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
adf0: 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  MP_JOURNAL     0
ae00: 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46  x00001000  /* VF
ae10: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
ae20: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55  e SQLITE_OPEN_SU
ae30: 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30  BJOURNAL       0
ae40: 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46  x00002000  /* VF
ae50: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
ae60: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
ae70: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30  STER_JOURNAL   0
ae80: 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46  x00004000  /* VF
ae90: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
aea0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f  e SQLITE_OPEN_NO
aeb0: 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30  MUTEX          0
aec0: 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b  x00008000  /* Ok
aed0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
aee0: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
aef0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55  e SQLITE_OPEN_FU
af00: 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30  LLMUTEX        0
af10: 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b  x00010000  /* Ok
af20: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
af30: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
af40: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  e SQLITE_OPEN_SH
af50: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30  AREDCACHE      0
af60: 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b  x00020000  /* Ok
af70: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
af80: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
af90: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
afa0: 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30  IVATECACHE     0
afb0: 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b  x00040000  /* Ok
afc0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
afd0: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
afe0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41  e SQLITE_OPEN_WA
aff0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  L              0
b000: 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46  x00080000  /* VF
b010: 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65  S only */../* Re
b020: 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20  served:         
b030: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b040: 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f  0x00F00000 */../
b050: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
b060: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69  evice Characteri
b070: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  stics.**.** The 
b080: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
b090: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66  istics method of
b0a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
b0b0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
b0c0: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
b0d0: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
b0e0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73  a vector of thes
b0f0: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20  e.** bit values 
b100: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63  expressing I/O c
b110: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f  haracteristics o
b120: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61  f the mass stora
b130: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  ge.** device tha
b140: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65  t holds the file
b150: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
b160: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
b170: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a  * refers to..**.
b180: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
b190: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
b1a0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
b1b0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
b1c0: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
b1d0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
b1e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
b1f0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
b200: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
b210: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
b220: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
b230: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
b240: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
b250: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
b260: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
b270: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
b280: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
b290: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
b2a0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
b2b0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
b2c0: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
b2d0: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
b2e0: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
b2f0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
b300: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
b310: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
b320: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
b330: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
b340: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
b350: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
b360: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
b370: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
b380: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
b390: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
b3a0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
b3b0: 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53  xWrite().  The S
b3c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
b3d0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
b3e0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
b3f0: 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62  hat.** after reb
b400: 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  oot following a 
b410: 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c  crash or power l
b420: 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79  oss, the only by
b430: 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65  tes in a.** file
b440: 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74   that were writt
b450: 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63  en at the applic
b460: 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68  ation level migh
b470: 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a  t have changed.*
b480: 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63  * and that adjac
b490: 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20  ent bytes, even 
b4a0: 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65  bytes within the
b4b0: 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65   same sector are
b4c0: 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74  .** guaranteed t
b4d0: 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a  o be unchanged..
b4e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b4f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
b500: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
b510: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
b520: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
b530: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
b540: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
b550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b560: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
b570: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
b580: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
b590: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
b5a0: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
b5b0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
b5c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
b5d0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
b5e0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
b5f0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
b600: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
b610: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
b620: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
b630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
b640: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
b650: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
b660: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
b670: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
b680: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
b690: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
b6a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
b6b0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
b6c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
b6d0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b6e0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
b6f0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
b700: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
b710: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
b720: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
b730: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
b740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
b750: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
b760: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
b770: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
b780: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
b790: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
b7a0: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f     0x00001000../
b7b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
b7c0: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
b7d0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
b7e0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
b7f0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
b800: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
b810: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
b820: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
b830: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
b840: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
b850: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
b860: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
b870: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
b880: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
b890: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
b8a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
b8b0: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
b8c0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
b8d0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
b8e0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
b8f0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
b900: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
b910: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
b920: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
b930: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b940: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
b950: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
b960: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
b970: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
b980: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
b990: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
b9a0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
b9b0: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
b9c0: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
b9d0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
b9e0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
b9f0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
ba00: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
ba10: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
ba20: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
ba30: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
ba40: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
ba50: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
ba60: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
ba70: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
ba80: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
ba90: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
baa0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
bab0: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
bac0: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
bad0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
bae0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
baf0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
bb00: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
bb10: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
bb20: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
bb30: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
bb40: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
bb50: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
bb60: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
bb70: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
bb80: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
bb90: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
bba0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
bbb0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
bbc0: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
bbd0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
bbe0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
bbf0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
bc00: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
bc10: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
bc20: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
bc30: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
bc40: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
bc50: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
bc60: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
bc70: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
bc80: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
bc90: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
bca0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
bcb0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
bcc0: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
bcd0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
bce0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
bcf0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
bd00: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
bd10: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
bd20: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
bd30: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
bd40: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
bd50: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
bd60: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
bd70: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
bd80: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
bd90: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
bda0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
bdb0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
bdc0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
bdd0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
bde0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
bdf0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
be00: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
be10: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
be20: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
be30: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
be40: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
be50: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
be60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
be70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
be80: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
be90: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
bea0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
beb0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
bec0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
bed0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
bee0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
bef0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
bf00: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
bf10: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
bf20: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
bf30: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
bf40: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
bf50: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
bf60: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
bf70: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
bf80: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
bf90: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
bfa0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
bfb0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
bfc0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
bfd0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
bfe0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
bff0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
c000: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
c010: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
c020: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
c030: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
c040: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
c050: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
c060: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
c070: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
c080: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
c090: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
c0a0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
c0b0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
c0c0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
c0d0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
c0e0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
c0f0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
c100: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c110: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
c120: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
c130: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
c140: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
c150: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
c160: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
c170: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
c180: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
c190: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
c1a0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
c1b0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
c1c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
c1d0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
c1e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
c1f0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
c200: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
c210: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
c220: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
c230: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
c240: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
c250: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
c260: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
c270: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
c280: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
c290: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
c2a0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
c2b0: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
c2c0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
c2d0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
c2e0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
c2f0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
c300: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
c310: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
c320: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
c330: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
c340: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
c350: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
c360: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
c370: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
c380: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
c390: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
c3a0: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
c3b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
c3c0: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
c3d0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
c3e0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
c3f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
c400: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
c410: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
c420: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
c430: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
c440: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
c450: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
c460: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
c470: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
c480: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
c490: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
c4a0: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
c4b0: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
c4c0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
c4d0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
c4e0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
c4f0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
c500: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
c510: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
c520: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
c530: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
c540: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
c550: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
c560: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
c570: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
c580: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
c590: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
c5a0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
c5b0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
c5c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
c5d0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
c5e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
c5f0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
c600: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
c610: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
c620: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
c630: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
c640: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
c650: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
c660: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
c670: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
c680: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
c690: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
c6a0: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
c6b0: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
c6c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
c6d0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
c6e0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
c6f0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
c700: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
c710: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
c720: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
c730: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
c740: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
c750: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
c760: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
c770: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
c780: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
c790: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
c7a0: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
c7b0: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
c7c0: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
c7d0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
c7e0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
c7f0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
c800: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
c810: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
c820: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
c830: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
c840: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
c850: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
c860: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
c870: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
c880: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
c890: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
c8a0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
c8b0: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
c8c0: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
c8d0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
c8e0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
c8f0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
c900: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
c910: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
c920: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
c930: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
c940: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
c950: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
c960: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
c970: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
c980: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
c990: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
c9a0: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
c9b0: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
c9c0: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
c9d0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
c9e0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
c9f0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
ca00: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
ca10: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
ca20: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
ca30: 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f  e..** A [SQLITE_
ca40: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
ca50: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65  | list of opcode
ca60: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  s] less than 100
ca70: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
ca80: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
ca90: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73  hat define a cus
caa0: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  tom xFileControl
cab0: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75   method should u
cac0: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72  se opcodes.** gr
cad0: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74  eater than 100 t
cae0: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74  o avoid conflict
caf0: 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  s.  VFS implemen
cb00: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a  tations should.*
cb10: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
cb20: 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66  _NOTFOUND] for f
cb30: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
cb40: 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f  des that they do
cb50: 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a   not.** recogniz
cb60: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  e..**.** The xSe
cb70: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
cb80: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
cb90: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
cba0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
cbb0: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
cbc0: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
cbd0: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
cbe0: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
cbf0: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
cc00: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
cc10: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
cc20: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
cc30: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
cc40: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
cc50: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
cc60: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
cc70: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
cc80: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
cc90: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
cca0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ccb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
ccc0: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69  P_ATOMIC].** <li
ccd0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
cce0: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c  ATOMIC512].** <l
ccf0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
cd00: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC1K].** <l
cd10: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
cd20: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC2K].** <l
cd30: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
cd40: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC4K].** <l
cd50: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
cd60: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC8K].** <l
cd70: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
cd80: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c  _ATOMIC16K].** <
cd90: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
cda0: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20  P_ATOMIC32K].** 
cdb0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
cdc0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a  AP_ATOMIC64K].**
cdd0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
cde0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d  CAP_SAFE_APPEND]
cdf0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
ce00: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
ce10: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  L].** </ul>.**.*
ce20: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
ce30: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
ce40: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
ce50: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
ce60: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
ce70: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
ce80: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
ce90: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
cea0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
ceb0: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
cec0: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
ced0: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
cee0: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
cef0: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
cf00: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
cf10: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
cf20: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
cf30: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
cf40: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
cf50: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
cf60: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
cf70: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
cf80: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
cf90: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
cfa0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
cfb0: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
cfc0: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
cfd0: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
cfe0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
cff0: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
d000: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
d010: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
d020: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
d030: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
d040: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
d050: 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49  Write()..**.** I
d060: 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e  f xRead() return
d070: 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  s SQLITE_IOERR_S
d080: 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73  HORT_READ it mus
d090: 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69  t also fill.** i
d0a0: 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72  n the unread por
d0b0: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66  tions of the buf
d0c0: 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20  fer with zeros. 
d0d0: 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66   A VFS that.** f
d0e0: 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  ails to zero-fil
d0f0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69  l short reads mi
d100: 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b  ght seem to work
d110: 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
d120: 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66  ailure to zero-f
d130: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
d140: 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20  will eventually 
d150: 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62  lead to.** datab
d160: 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  ase corruption..
d170: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
d180: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
d190: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
d1a0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
d1b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
d1c0: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
d1d0: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
d1e0: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
d1f0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
d200: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
d210: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
d220: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
d230: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
d240: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
d250: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
d260: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
d270: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
d280: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
d290: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
d2a0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
d2b0: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
d2c0: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
d2d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
d2e0: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
d2f0: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
d300: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
d310: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
d320: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
d330: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
d340: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
d350: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
d360: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
d370: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
d380: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
d390: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
d3a0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
d3b0: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
d3c0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
d3d0: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
d3e0: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
d3f0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
d400: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
d410: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
d420: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
d430: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
d440: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
d450: 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f  for version 1 */
d460: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70  .  int (*xShmMap
d470: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
d480: 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67   int iPg, int pg
d490: 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f  sz, int, void vo
d4a0: 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74  latile**);.  int
d4b0: 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c   (*xShmLock)(sql
d4c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
d4d0: 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69  offset, int n, i
d4e0: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69  nt flags);.  voi
d4f0: 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29  d (*xShmBarrier)
d500: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
d510: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d  .  int (*xShmUnm
d520: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
d530: 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61  *, int deleteFla
d540: 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  g);.  /* Methods
d550: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
d560: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a   for version 2 *
d570: 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68  /.  int (*xFetch
d580: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
d590: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
d5a0: 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20  Ofst, int iAmt, 
d5b0: 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e  void **pp);.  in
d5c0: 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71  t (*xUnfetch)(sq
d5d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
d5e0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
d5f0: 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a  , void *p);.  /*
d600: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
d610: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
d620: 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41  sion 3 */.  /* A
d630: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
d640: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
d650: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
d660: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
d670: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
d680: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
d690: 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  pcodes.**.** The
d6a0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
d6b0: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
d6c0: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
d6d0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
d6e0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
d6f0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
d700: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
d710: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
d720: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
d730: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
d740: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
d750: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
d760: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
d770: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
d780: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
d790: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
d7a0: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
d7b0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
d7c0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
d7d0: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
d7e0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
d7f0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
d800: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
d810: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
d820: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
d830: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
d840: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
d850: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
d860: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
d870: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
d880: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
d890: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
d8a0: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
d8b0: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
d8c0: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
d8d0: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
d8e0: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  * is defined..**
d8f0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53   <ul>.** <li>[[S
d900: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
d910: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
d920: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
d930: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
d940: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
d950: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
d960: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
d970: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
d980: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
d990: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
d9a0: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
d9b0: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
d9c0: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
d9d0: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
d9e0: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
d9f0: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
da00: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
da10: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
da20: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
da30: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
da40: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
da50: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
da60: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
da70: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
da80: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
da90: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
daa0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
dab0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
dac0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
dad0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
dae0: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
daf0: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
db00: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
db10: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
db20: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
db30: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
db40: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
db50: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
db60: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
db70: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
db80: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
db90: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
dba0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
dbb0: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
dbc0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
dbd0: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
dbe0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
dbf0: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
dc00: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
dc10: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
dc20: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
dc30: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
dc40: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
dc50: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
dc60: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
dc70: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
dc80: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
dc90: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
dca0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
dcb0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
dcc0: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
dcd0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
dce0: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
dcf0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
dd00: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
dd10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
dd20: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
dd30: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
dd40: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
dd50: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
dd60: 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  See the [sqlite3
dd70: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
dd80: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
dd90: 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
dda0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
ddb0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
ddc0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
ddd0: 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b  TED]].** ^(The [
dde0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
ddf0: 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64  C_OMITTED] opcod
de00: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
de10: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20  nternally by.** 
de20: 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20  SQLite and sent 
de30: 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20  to all VFSes in 
de40: 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20  place of a call 
de50: 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  to the xSync met
de60: 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  hod.** when the 
de70: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
de80: 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20  ion has [PRAGMA 
de90: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74  synchronous] set
dea0: 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f   to OFF.)^.** So
deb0: 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  me specialized V
dec0: 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73  FSes need this s
ded0: 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74  ignal in order t
dee0: 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63  o operate correc
def0: 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41  tly.** when [PRA
df00: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
df10: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
df20: 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74  nous=OFF] is set
df30: 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56  , but most .** V
df40: 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64  FSes do not need
df50: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64   this signal and
df60: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
df70: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
df80: 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ode..** Applicat
df90: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
dfa0: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  call [sqlite3_fi
dfb0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
dfc0: 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  th this.** opcod
dfd0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
dfe0: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70  y disrupt the op
dff0: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
e000: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
e010: 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75  .** that do requ
e020: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
e030: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
e040: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
e050: 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  Y]].** ^The [SQL
e060: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
e070: 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65  AV_RETRY] opcode
e080: 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
e090: 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a  igure automatic.
e0a0: 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20  ** retry counts 
e0b0: 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f  and intervals fo
e0c0: 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49  r certain disk I
e0d0: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f  /O operations fo
e0e0: 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73  r the.** windows
e0f0: 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20   [VFS] in order 
e100: 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73  to provide robus
e110: 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65  tness in the pre
e120: 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69  sence of.** anti
e130: 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e  -virus programs.
e140: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
e150: 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69  e windows VFS wi
e160: 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65  ll retry file re
e170: 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74  ad,.** file writ
e180: 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65  e, and file dele
e190: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70  te operations up
e1a0: 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69   to 10 times, wi
e1b0: 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66  th a delay.** of
e1c0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
e1d0: 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73   before the firs
e1e0: 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68  t retry and with
e1f0: 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65   the delay incre
e200: 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61  asing.** by an a
e210: 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c  dditional 25 mil
e220: 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65  liseconds with e
e230: 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72  ach subsequent r
e240: 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  etry.  This.** o
e250: 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65  pcode allows the
e260: 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31  se two values (1
e270: 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35  0 retries and 25
e280: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
e290: 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65   delay).** to be
e2a0: 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20   adjusted.  The 
e2b0: 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67  values are chang
e2c0: 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62  ed for all datab
e2d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
e2e0: 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  ** within the sa
e2f0: 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65  me process.  The
e300: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
e310: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72  ointer to an arr
e320: 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74  ay of two.** int
e330: 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20  egers where the 
e340: 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20  first integer i 
e350: 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f  the new retry co
e360: 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  unt and the seco
e370: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73  nd.** integer is
e380: 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20   the delay.  If 
e390: 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69  either integer i
e3a0: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
e3b0: 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
e3c0: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62  is not changed b
e3d0: 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70  ut instead the p
e3e0: 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
e3f0: 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72  at setting is wr
e400: 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68  itten.** into th
e410: 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61  e array entry, a
e420: 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72  llowing the curr
e430: 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e  ent retry settin
e440: 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65  gs to be.** inte
e450: 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a  rrogated.  The z
e460: 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  DbName parameter
e470: 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
e480: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
e490: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
e4a0: 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  L]].** ^The [SQL
e4b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
e4c0: 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73  T_WAL] opcode is
e4d0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
e4e0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
e4f0: 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57  sistent [WAL | W
e500: 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20  rite Ahead Log] 
e510: 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66  setting.  By def
e520: 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69  ault, the auxili
e530: 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65  ary.** write ahe
e540: 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65  ad log and share
e550: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75  d memory files u
e560: 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74  sed for transact
e570: 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61  ion control.** a
e580: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
e590: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
e5a0: 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74  e latest connect
e5b0: 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62  ion to the datab
e5c0: 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20  ase.** closes.  
e5d0: 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65  Setting persiste
e5e0: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73  nt WAL mode caus
e5f0: 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74  es those files t
e600: 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a  o persist after.
e610: 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69  ** close.  Persi
e620: 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20  sting the files 
e630: 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f  is useful when o
e640: 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74  ther processes t
e650: 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61  hat do not.** ha
e660: 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73  ve write permiss
e670: 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63  ion on the direc
e680: 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  tory containing 
e690: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
e6a0: 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61  e want.** to rea
e6b0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  d the database f
e6c0: 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20  ile, as the WAL 
e6d0: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
e6e0: 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69  y files must exi
e6f0: 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66  st.** in order f
e700: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
e710: 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20  to be readable. 
e720: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
e730: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
e740: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
e750: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
e760: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
e770: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
e780: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
e790: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
e7a0: 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65  disable persiste
e7b0: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31  nt WAL mode or 1
e7c0: 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69   to enable persi
e7d0: 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64  stent.** WAL mod
e7e0: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
e7f0: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
e800: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
e810: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
e820: 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74  t.** WAL persist
e830: 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  ence setting..**
e840: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
e850: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
e860: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
e870: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
e880: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
e890: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
e8a0: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
e8b0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
e8c0: 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73  rsistent "powers
e8d0: 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f  afe-overwrite" o
e8e0: 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67  r "PSOW" setting
e8f0: 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74  .  The PSOW sett
e900: 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65  ing.** determine
e910: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f  s the [SQLITE_IO
e920: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
e930: 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20  ERWRITE] bit of 
e940: 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68  the.** xDeviceCh
e950: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
e960: 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74  thods. The fourt
e970: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
e980: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
e990: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
e9a0: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
e9b0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
e9c0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
e9d0: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
e9e0: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65   0 to disable ze
e9f0: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f  ro-damage mode o
ea00: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65  r 1 to enable ze
ea10: 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64  ro-damage.** mod
ea20: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
ea30: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
ea40: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
ea50: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
ea60: 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65  t.** zero-damage
ea70: 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a   mode setting..*
ea80: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ea90: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
eaa0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
eab0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
eac0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  ITE] opcode is i
ead0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
eae0: 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a   after opening.*
eaf0: 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61  * a write transa
eb00: 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74  ction to indicat
eb10: 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69  e that, unless i
eb20: 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t is rolled back
eb30: 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61   for some.** rea
eb40: 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20  son, the entire 
eb50: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
eb60: 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ll be overwritte
eb70: 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  n by the current
eb80: 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e   .** transaction
eb90: 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62  . This is used b
eba0: 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69  y VACUUM operati
ebb0: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ons..**.** <li>[
ebc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
ebd0: 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  SNAME]].** ^The 
ebe0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
ebf0: 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61  SNAME] opcode ca
ec00: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
ec10: 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
ec20: 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20  .** all [VFSes] 
ec30: 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b  in the VFS stack
ec40: 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65  .  The names are
ec50: 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d   of all VFS shim
ec60: 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e  s and the.** fin
ec70: 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20  al bottom-level 
ec80: 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20  VFS are written 
ec90: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
eca0: 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
ecb0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
ecc0: 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20   and the result 
ecd0: 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  is stored in the
ece0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a   char* variable.
ecf0: 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72  ** that the four
ed00: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
ed10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
ed20: 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20  ntrol()] points 
ed30: 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65  to..** The calle
ed40: 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  r is responsible
ed50: 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65   for freeing the
ed60: 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e   memory when don
ed70: 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61  e.  As with.** a
ed80: 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ll file-control 
ed90: 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69  actions, there i
eda0: 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74  s no guarantee t
edb0: 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63  hat this will ac
edc0: 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79  tually.** do any
edd0: 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20  thing.  Callers 
ede0: 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a  should initializ
edf0: 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  e the char* vari
ee00: 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a  able to a NULL.*
ee10: 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73  * pointer in cas
ee20: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
ee30: 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  rol is not imple
ee40: 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69  mented.  This fi
ee50: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73  le-control.** is
ee60: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69   intended for di
ee70: 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c  agnostic use onl
ee80: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
ee90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
eea0: 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65  MA]].** ^Wheneve
eeb0: 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  r a [PRAGMA] sta
eec0: 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64  tement is parsed
eed0: 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e  , an [SQLITE_FCN
eee0: 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66  TL_PRAGMA] .** f
eef0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73  ile control is s
ef00: 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20  ent to the open 
ef10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
ef20: 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64  bject correspond
ef30: 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61  ing.** to the da
ef40: 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77  tabase file to w
ef50: 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20  hich the pragma 
ef60: 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73  statement refers
ef70: 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a  . ^The argument.
ef80: 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54  ** to the [SQLIT
ef90: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
efa0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
efb0: 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70  an array of.** p
efc0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
efd0: 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77  gs (char**) in w
efe0: 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20  hich the second 
eff0: 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  element of the a
f000: 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e  rray.** is the n
f010: 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ame of the pragm
f020: 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20  a and the third 
f030: 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61  element is the a
f040: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
f050: 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c  * pragma or NULL
f060: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68   if the pragma h
f070: 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20  as no argument. 
f080: 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f   ^The handler fo
f090: 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r an.** [SQLITE_
f0a0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
f0b0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f  le control can o
f0c0: 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74  ptionally make t
f0d0: 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74  he first element
f0e0: 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a  .** of the char*
f0f0: 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  * argument point
f100: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74   to a string obt
f110: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
f120: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a  te3_mprintf()].*
f130: 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c  * or the equival
f140: 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72  ent and that str
f150: 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20  ing will become 
f160: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
f170: 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74  e pragma or.** t
f180: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
f190: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66   if the pragma f
f1a0: 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a  ails. ^If the.**
f1b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
f1c0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
f1d0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
f1e0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
f1f0: 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b  hen normal .** [
f200: 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69  PRAGMA] processi
f210: 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e  ng continues.  ^
f220: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
f230: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
f240: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
f250: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
f260: 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65  , then the parse
f270: 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  r assumes that t
f280: 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61  he.** VFS has ha
f290: 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41  ndled the PRAGMA
f2a0: 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20   itself and the 
f2b0: 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73  parser generates
f2c0: 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70   a no-op.** prep
f2d0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20  ared statement. 
f2e0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
f2f0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
f300: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
f310: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c  rns.** any resul
f320: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61  t code other tha
f330: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  n [SQLITE_OK] or
f340: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
f350: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  D], that means.*
f360: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65  * that the VFS e
f370: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72  ncountered an er
f380: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69  ror while handli
f390: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20  ng the [PRAGMA] 
f3a0: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  and the.** compi
f3b0: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52  lation of the PR
f3c0: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20  AGMA fails with 
f3d0: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20  an error.  ^The 
f3e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
f3f0: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
f400: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20  ntrol occurs at 
f410: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
f420: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
f430: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73  t analysis and s
f440: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20  o.** it is able 
f450: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c  to override buil
f460: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74  t-in [PRAGMA] st
f470: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
f480: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
f490: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d  TL_BUSYHANDLER]]
f4a0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
f4b0: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
f4c0: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  ER].** file-cont
f4d0: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
f4e0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
f4f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
f500: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
f510: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
f520: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
f530: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
f540: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
f550: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
f560: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
f570: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
f580: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
f590: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
f5a0: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
f5b0: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
f5c0: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
f5d0: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
f5e0: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
f5f0: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
f600: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
f610: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
f620: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
f630: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
f640: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
f650: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
f660: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
f670: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
f680: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
f690: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
f6a0: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
f6b0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
f6c0: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
f6d0: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
f6e0: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
f6f0: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
f700: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
f710: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
f720: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
f730: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
f740: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
f750: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
f760: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
f770: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b  can invoke the [
f780: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
f790: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d  PFILENAME] file-
f7a0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61  control.** to ha
f7b0: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61  ve SQLite genera
f7c0: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  te a.** temporar
f7d0: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67  y filename using
f7e0: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
f7f0: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c  thm that is foll
f800: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65  owed to generate
f810: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
f820: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50  lenames for TEMP
f830: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65   tables and othe
f840: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e  r internal uses.
f850: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e    The.** argumen
f860: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68  t should be a ch
f870: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  ar** which will 
f880: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  be filled with t
f890: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
f8a0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
f8b0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
f8c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
f8d0: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72  ()].  The caller
f8e0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b   should.** invok
f8f0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
f900: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  )] on the result
f910: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   to avoid a memo
f920: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c  ry leak..**.** <
f930: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
f940: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  L_MMAP_SIZE]].**
f950: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
f960: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
f970: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
f980: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73  ed to query or s
f990: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75  et the.** maximu
f9a0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
f9b0: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75  s that will be u
f9c0: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d  sed for memory-m
f9d0: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68  apped I/O..** Th
f9e0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
f9f0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
fa00: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74  ue of type sqlit
fa10: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a  e3_int64 that.**
fa20: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20   is an advisory 
fa30: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
fa40: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  f bytes in the f
fa50: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61  ile to memory ma
fa60: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  p.  The.** point
fa70: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  er is overwritte
fa80: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76  n with the old v
fa90: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74  alue.  The limit
faa0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
fab0: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  if.** the value 
fac0: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74  originally point
fad0: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76  ed to is negativ
fae0: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75  e, and so the cu
faf0: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20  rrent limit .** 
fb00: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62  can be queried b
fb10: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70  y passing in a p
fb20: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61  ointer to a nega
fb30: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68  tive number.  Th
fb40: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  is.** file-contr
fb50: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  ol is used inter
fb60: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65  nally to impleme
fb70: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  nt [PRAGMA mmap_
fb80: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75  size]..**.** </u
fb90: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
fba0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
fbb0: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
fbc0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
fbd0: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_GET_LOCKPROX
fbe0: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20  YFILE           
fbf0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
fc00: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
fc10: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
fc20: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
fc30: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
fc40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
fc50: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
fc60: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
fc70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
fc80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fc90: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
fca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
fcb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
fcc0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
fcd0: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
fce0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
fcf0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
fd00: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
fd10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
fd20: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
fd30: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
fd40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
fd50: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
fd60: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
fd70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
fd80: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
fd90: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
fda0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
fdb0: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
fdc0: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
fdd0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
fde0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
fdf0: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
fe00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
fe10: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
fe20: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
fe30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
fe40: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
fe50: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
fe60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
fe70: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
fe80: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
fe90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
fea0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
feb0: 20 20 31 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    18../*.** CAPI
fec0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
fed0: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
fee0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
fef0: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
ff00: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
ff10: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
ff20: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
ff30: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
ff40: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
ff50: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
ff60: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
ff70: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
ff80: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
ff90: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
ffa0: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
ffb0: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
ffc0: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
ffd0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
ffe0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
fff0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
10000 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
10010 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
10020 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
10030 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
10040 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
10050 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
10060 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
10070 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
10080 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
10090 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
100a0 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
100b0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
100c0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
100d0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
100e0 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
100f0 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
10100 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
10110 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
10120 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65  le system".  See
10130 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56  .** the [VFS | V
10140 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  FS documentation
10150 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e  ] for further in
10160 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
10170 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   The value of th
10180 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
10190 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20   is initially 1 
101a0 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
101b0 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76  r in.** future v
101c0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
101d0 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
101e0 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
101f0 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
10200 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
10210 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
10220 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e  is increased.  N
10230 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72  ote that the str
10240 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65  ucture.** of the
10250 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
10260 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74  ect changes in t
10270 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
10280 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  etween.** SQLite
10290 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61   version 3.5.9 a
102a0 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74  nd 3.6.0 and yet
102b0 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
102c0 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d  eld was not.** m
102d0 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  odified..**.** T
102e0 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c  he szOsFile fiel
102f0 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  d is the size of
10300 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20   the subclassed 
10310 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a  [sqlite3_file].*
10320 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64  * structure used
10330 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d   by this VFS.  m
10340 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65  xPathname is the
10350 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
10360 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65  of.** a pathname
10370 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a   in this VFS..**
10380 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73  .** Registered s
10390 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
103a0 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61  ts are kept on a
103b0 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72   linked list for
103c0 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e  med by.** the pN
103d0 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ext pointer.  Th
103e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  e [sqlite3_vfs_r
103f0 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e  egister()].** an
10400 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  d [sqlite3_vfs_u
10410 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74  nregister()] int
10420 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74  erfaces manage t
10430 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61  his list.** in a
10440 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79   thread-safe way
10450 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
10460 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65  vfs_find()] inte
10470 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65  rface.** searche
10480 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69  s the list.  Nei
10490 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  ther the applica
104a0 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68  tion code nor th
104b0 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65  e VFS.** impleme
104c0 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  ntation should u
104d0 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  se the pNext poi
104e0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
104f0 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74  pNext field is t
10500 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e  he only field in
10510 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
10520 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68  .** structure th
10530 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  at SQLite will e
10540 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c  ver modify.  SQL
10550 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63  ite will only ac
10560 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66  cess.** or modif
10570 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69  y this field whi
10580 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
10590 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
105a0 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
105b0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
105c0 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
105d0 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65  thing within the
105e0 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
105f0 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20  object once the 
10600 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20  object has been 
10610 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a  registered..**.*
10620 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
10630 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
10640 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
10650 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
10660 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
10670 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
10680 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  odules..**.** [[
10690 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
106a0 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  n]].** ^SQLite g
106b0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
106c0 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
106d0 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
106e0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
106f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
10700 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
10710 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
10720 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
10730 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
10740 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
10750 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
10760 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
10770 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
10780 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
10790 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
107a0 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
107b0 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
107c0 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65  .** 11 alphanume
107d0 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
107e0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
107f0 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
10800 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
10810 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
10820 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
10830 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
10840 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
10850 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
10860 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
10870 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
10880 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
10890 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
108a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
108b0 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
108c0 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
108d0 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
108e0 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
108f0 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
10900 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
10910 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
10920 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
10930 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
10940 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
10950 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
10960 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
10970 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
10980 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
10990 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
109a0 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
109b0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
109c0 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
109d0 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
109e0 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
109f0 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
10a00 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
10a10 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
10a20 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
10a30 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
10a40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
10a50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
10a60 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
10a70 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
10a80 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
10a90 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
10aa0 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
10ab0 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
10ac0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
10ad0 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
10ae0 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
10af0 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
10b00 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
10b10 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
10b20 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
10b30 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
10b40 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
10b50 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
10b60 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
10b70 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
10b80 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
10b90 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
10ba0 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
10bb0 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
10bc0 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
10bd0 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
10be0 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
10bf0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
10c00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
10c10 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
10c20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
10c30 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
10c40 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
10c50 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
10c60 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
10c70 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
10c80 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
10c90 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
10ca0 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
10cb0 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
10cc0 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
10cd0 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
10ce0 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
10cf0 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
10d00 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
10d10 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
10d20 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
10d30 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
10d40 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
10d50 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
10d60 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
10d70 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
10d80 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
10d90 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
10da0 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
10db0 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
10dc0 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
10dd0 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
10de0 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
10df0 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
10e00 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
10e10 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
10e20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
10e30 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
10e40 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
10e50 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
10e60 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
10e70 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
10e80 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
10e90 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
10ea0 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
10eb0 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
10ec0 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
10ed0 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
10ee0 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
10ef0 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
10f00 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
10f10 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
10f20 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
10f30 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
10f40 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
10f50 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
10f60 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
10f70 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
10f80 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
10f90 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
10fa0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
10fb0 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
10fc0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
10fd0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
10fe0 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
10ff0 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
11000 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
11010 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
11020 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
11030 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
11040 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
11050 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
11060 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
11070 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
11080 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
11090 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
110a0 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
110b0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
110c0 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
110d0 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
110e0 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
110f0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
11100 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
11110 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
11120 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
11130 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
11140 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
11150 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
11160 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
11170 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
11180 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
11190 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
111a0 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
111b0 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
111c0 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
111d0 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
111e0 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
111f0 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
11200 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
11210 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
11220 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
11230 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
11240 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
11250 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
11260 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
11270 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
11280 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
11290 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
112a0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
112b0 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
112c0 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
112d0 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
112e0 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
112f0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
11300 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
11310 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
11320 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
11330 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
11340 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
11350 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
11360 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
11370 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
11380 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
11390 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
113a0 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
113b0 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
113c0 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
113d0 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
113e0 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
113f0 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
11400 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
11410 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
11420 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
11430 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
11440 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
11450 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
11460 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
11470 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
11480 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
11490 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
114a0 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
114b0 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
114c0 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41  [[sqlite3_vfs.xA
114d0 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20  ccess]].** ^The 
114e0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
114f0 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
11500 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
11510 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
11520 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
11530 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
11540 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
11550 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
11560 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
11570 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
11580 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
11590 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
115a0 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
115b0 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
115c0 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
115d0 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
115e0 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
115f0 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
11600 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
11610 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
11620 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
11630 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
11640 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
11650 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
11660 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
11670 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
11680 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
11690 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
116a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
116b0 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
116c0 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
116d0 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
116e0 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
116f0 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
11700 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
11710 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
11720 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
11730 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
11740 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
11750 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
11760 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
11770 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
11780 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
11790 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
117a0 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
117b0 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
117c0 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
117d0 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  ), xCurrentTime(
117e0 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
117f0 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e  imeInt64().** in
11800 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74  terfaces are not
11810 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74   strictly a part
11820 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74   of the filesyst
11830 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65  em, but they are
11840 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  .** included in 
11850 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72  the VFS structur
11860 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65  e for completene
11870 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ss..** The xRand
11880 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f  omness() functio
11890 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  n attempts to re
118a0 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65  turn nBytes byte
118b0 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61  s.** of good-qua
118c0 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20  lity randomness 
118d0 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
118e0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a  return value is.
118f0 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75  ** the actual nu
11900 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
11910 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
11920 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c  ined..** The xSl
11930 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
11940 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ses the calling 
11950 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20  thread to sleep 
11960 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20  for at.** least 
11970 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
11980 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e  croseconds given
11990 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  .  ^The xCurrent
119a0 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
119b0 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
119c0 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
119d0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
119e0 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a  e and time as.**
119f0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
11a00 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65  t value..** ^The
11a10 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
11a20 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  64() method retu
11a30 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67  rns, as an integ
11a40 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a  er, the Julian.*
11a50 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c  * Day Number mul
11a60 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30  tiplied by 86400
11a70 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20  000 (the number 
11a80 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
11a90 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72  in .** a 24-hour
11aa0 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c   day).  .** ^SQL
11ab0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
11ac0 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
11ad0 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67  64() method to g
11ae0 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  et the current.*
11af0 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  * date and time 
11b00 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69  if that method i
11b10 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20  s available (if 
11b20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72  iVersion is 2 or
11b30 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64   .** greater and
11b40 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
11b50 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
11b60 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c  L) and will fall
11b70 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72   back.** to xCur
11b80 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43  rentTime() if xC
11b90 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
11ba0 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  ) is unavailable
11bb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65  ..**.** ^The xSe
11bc0 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78  tSystemCall(), x
11bd0 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  GetSystemCall(),
11be0 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d   and xNestSystem
11bf0 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  Call() interface
11c00 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65  s.** are not use
11c10 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20  d by the SQLite 
11c20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74  core.  These opt
11c30 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ional interfaces
11c40 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a   are provided.**
11c50 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74   by some VFSes t
11c60 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73  o facilitate tes
11c70 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20  ting of the VFS 
11c80 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64  code. By overrid
11c90 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63  ing .** system c
11ca0 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69  alls with functi
11cb0 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f  ons under its co
11cc0 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72  ntrol, a test pr
11cd0 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d  ogram can.** sim
11ce0 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64  ulate faults and
11cf0 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e   error condition
11d00 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68  s that would oth
11d10 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63  erwise be diffic
11d20 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73  ult.** or imposs
11d30 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20  ible to induce. 
11d40 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74   The set of syst
11d50 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61  em calls that ca
11d60 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a  n be overridden.
11d70 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f  ** varies from o
11d80 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65  ne VFS to anothe
11d90 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20  r, and from one 
11da0 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73  version of the s
11db0 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a  ame VFS to the.*
11dc0 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
11dd0 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74  tions that use t
11de0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
11df0 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64  must be prepared
11e00 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61   for any.** or a
11e10 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ll of these inte
11e20 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c  rfaces to be NUL
11e30 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62  L or for their b
11e40 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67  ehavior to chang
11e50 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65  e.** from one re
11e60 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78  lease to the nex
11e70 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
11e80 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70   must not attemp
11e90 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61  t to access.** a
11ea0 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68  ny of these meth
11eb0 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73  ods if the iVers
11ec0 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69  ion of the VFS i
11ed0 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a  s less than 3..*
11ee0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
11ef0 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
11f00 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65  ite3_vfs;.typede
11f10 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
11f20 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f  _syscall_ptr)(vo
11f30 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  id);.struct sqli
11f40 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
11f50 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
11f60 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
11f70 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
11f80 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a   (currently 3) *
11f90 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
11fa0 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
11fb0 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
11fc0 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
11fd0 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
11fe0 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
11ff0 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
12000 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
12010 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
12020 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
12030 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
12040 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
12050 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
12060 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
12070 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
12080 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
12090 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
120a0 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
120b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
120c0 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
120d0 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
120e0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
120f0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
12100 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
12110 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
12120 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
12130 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
12140 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
12150 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
12160 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
12170 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
12180 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
12190 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
121a0 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
121b0 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
121c0 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
121d0 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
121e0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
121f0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
12200 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
12210 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
12220 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
12230 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
12240 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
12250 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
12260 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
12270 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
12280 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28  rrMsg);.  void (
12290 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
122a0 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
122b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
122c0 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f  ol))(void);.  vo
122d0 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
122e0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
122f0 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
12300 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
12310 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
12320 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
12330 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
12340 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
12350 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
12360 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
12370 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
12380 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
12390 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
123a0 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
123b0 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
123c0 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
123d0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
123e0 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f  e in version 1 o
123f0 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
12400 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66   object.  ** def
12410 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20  inition.  Those 
12420 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20  that follow are 
12430 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e  added in version
12440 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f   2 or later.  */
12450 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
12460 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69  tTimeInt64)(sqli
12470 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65  te3_vfs*, sqlite
12480 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a  3_int64*);.  /*.
12490 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
124a0 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
124b0 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f  rsions 1 and 2 o
124c0 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
124d0 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68   object..  ** Th
124e0 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f  ose below are fo
124f0 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20  r version 3 and 
12500 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20  greater..  */.  
12510 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d  int (*xSetSystem
12520 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
12530 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
12540 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
12550 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73  yscall_ptr);.  s
12560 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
12570 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43  tr (*xGetSystemC
12580 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
12590 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
125a0 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63  Name);.  const c
125b0 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74  har *(*xNextSyst
125c0 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
125d0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
125e0 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20   *zName);.  /*. 
125f0 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
12600 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
12610 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20  sions 1 through 
12620 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  3 of the sqlite_
12630 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
12640 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
12650 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
12660 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
12670 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
12680 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
12690 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
126a0 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a   this happens. .
126b0 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43    */.};../*.** C
126c0 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
126d0 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
126e0 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
126f0 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
12700 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
12710 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
12720 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
12730 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
12740 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
12750 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
12760 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
12770 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
12780 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
12790 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
127a0 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
127b0 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
127c0 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
127d0 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
127e0 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
127f0 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
12800 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
12810 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
12820 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
12830 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
12840 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
12850 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74  the named direct
12860 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64  ory is both read
12870 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
12880 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77  e.** (in other w
12890 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63  ords, if files c
128a0 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d  an be added, rem
128b0 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65  oved, and rename
128c0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
128d0 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54  directory)..** T
128e0 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
128f0 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74  _READWRITE const
12900 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ant is currently
12910 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68   used only by th
12920 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65  e.** [temp_store
12930 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
12940 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20  a], though this 
12950 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20  could change in 
12960 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
12970 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
12980 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
12990 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
129a0 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
129b0 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
129c0 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
129d0 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54  able.  The SQLIT
129e0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f  E_ACCESS_READ co
129f0 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72  nstant is.** cur
12a00 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74  rently unused, t
12a10 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62  hough it might b
12a20 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75  e used in a futu
12a30 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
12a40 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
12a50 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
12a60 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
12a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
12a80 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20  ESS_READWRITE 1 
12a90 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41    /* Used by PRA
12aa0 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64  GMA temp_store_d
12ab0 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66  irectory */.#def
12ac0 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
12ad0 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20  S_READ      2   
12ae0 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a  /* Unused */../*
12af0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
12b00 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d  ags for the xShm
12b10 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a  Lock VFS method.
12b20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
12b30 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ger constants de
12b40 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73  fine the various
12b50 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69   locking operati
12b60 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62  ons.** allowed b
12b70 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  y the xShmLock m
12b80 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65  ethod of [sqlite
12b90 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20  3_io_methods].  
12ba0 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  The.** following
12bb0 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65   are the only le
12bc0 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  gal combinations
12bd0 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65   of flags to the
12be0 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  .** xShmLock met
12bf0 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
12c00 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
12c10 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
12c20 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
12c30 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
12c40 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
12c50 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
12c60 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
12c70 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
12c80 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
12c90 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
12ca0 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
12cb0 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
12cc0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65   </ul>.**.** Whe
12cd0 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65  n unlocking, the
12ce0 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20   same SHARED or 
12cf0 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d  EXCLUSIVE flag m
12d00 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20  ust be supplied 
12d10 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20  as.** was given 
12d20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  no the correspon
12d30 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a  ding lock.  .**.
12d40 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
12d50 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73  method can trans
12d60 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e  ition between un
12d70 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45  locked and SHARE
12d80 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20  D or.** between 
12d90 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43  unlocked and EXC
12da0 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e  LUSIVE.  It cann
12db0 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  ot transition be
12dc0 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20  tween SHARED.** 
12dd0 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a  and EXCLUSIVE..*
12de0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12df0 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  _SHM_UNLOCK     
12e00 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
12e10 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20  TE_SHM_LOCK     
12e20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
12e30 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20  LITE_SHM_SHARED 
12e40 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
12e50 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
12e60 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a  SIVE    8../*.**
12e70 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d   CAPI3REF: Maxim
12e80 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65  um xShmLock inde
12e90 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d  x.**.** The xShm
12ea0 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b  Lock method on [
12eb0 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
12ec0 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75  ds] may use valu
12ed0 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  es.** between 0 
12ee0 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62  and this upper b
12ef0 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66  ound as its "off
12f00 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  set" argument..*
12f10 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
12f20 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74  e will never att
12f30 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20  empt to acquire 
12f40 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20  or release a.** 
12f50 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20  lock outside of 
12f60 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64  this range.*/.#d
12f70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
12f80 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a  _NLOCK        8.
12f90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12fa0 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
12fb0 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
12fc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
12fd0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12fe0 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69  routine initiali
12ff0 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74  zes the.** SQLit
13000 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65  e library.  ^The
13010 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
13020 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
13030 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
13040 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
13050 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
13060 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
13070 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ze()..** These r
13080 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69  outines are desi
13090 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70  gned to aid in p
130a0 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
130b0 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75  ation and.** shu
130c0 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65  tdown on embedde
130d0 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b  d systems.  Work
130e0 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74  station applicat
130f0 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ions using.** SQ
13100 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f  Lite normally do
13110 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76   not need to inv
13120 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68  oke either of th
13130 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
13140 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
13150 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
13160 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
13170 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
13180 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
13190 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
131a0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
131b0 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
131c0 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
131d0 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
131e0 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
131f0 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
13200 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
13210 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
13220 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
13230 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
13240 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66  .  ^(Only an eff
13250 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
13260 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
13270 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
13280 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
13290 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
132a0 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
132b0 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
132c0 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
132d0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73  e3_shutdown() is
132e0 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
132f0 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68  call if it is th
13300 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20  e first.** call 
13310 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
13320 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20  own() since the 
13330 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  last sqlite3_ini
13340 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e  tialize().  ^(On
13350 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69  ly.** an effecti
13360 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ve call to sqlit
13370 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f  e3_shutdown() do
13380 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c  es any deinitial
13390 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20  ization..** All 
133a0 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c  other valid call
133b0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  s to sqlite3_shu
133c0 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d  tdown() are harm
133d0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
133e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
133f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e  _initialize() in
13400 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61  terface is threa
13410 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74  dsafe, but sqlit
13420 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
13430 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71   is not.  The sq
13440 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
13450 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20   interface must 
13460 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66  only be called f
13470 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20  rom a.** single 
13480 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65  thread.  All ope
13490 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
134a0 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65  ections] must be
134b0 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a   closed and all.
134c0 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ** other SQLite 
134d0 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62  resources must b
134e0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72  e deallocated pr
134f0 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a  ior to invoking.
13500 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ** sqlite3_shutd
13510 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  own()..**.** Amo
13520 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
13530 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   ^sqlite3_initia
13540 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f  lize() will invo
13550 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
13560 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
13570 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68  rly, ^sqlite3_sh
13580 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c  utdown().** will
13590 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
135a0 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
135b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
135c0 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
135d0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
135e0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
135f0 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d  ..** ^If for som
13600 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65  e reason, sqlite
13610 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
13620 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74  s unable to init
13630 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69  ialize.** the li
13640 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69  brary (perhaps i
13650 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  t is unable to a
13660 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64  llocate a needed
13670 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a   resource such.*
13680 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74  * as a mutex) it
13690 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72   returns an [err
136a0 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74  or code] other t
136b0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  han [SQLITE_OK].
136c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
136d0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
136e0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
136f0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
13700 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
13710 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
13720 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
13730 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
13740 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
13750 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
13760 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
13770 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
13780 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
13790 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
137a0 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
137b0 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
137c0 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
137d0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
137e0 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
137f0 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
13800 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
13810 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
13820 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
13830 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77  * already.  ^How
13840 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
13850 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13860 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   the [SQLITE_OMI
13870 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63  T_AUTOINIT].** c
13880 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13890 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
138a0 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
138b0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
138c0 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
138d0 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
138e0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
138f0 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
13900 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
13910 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
13920 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
13930 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
13940 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
13950 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
13960 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
13970 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
13980 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
13990 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
139a0 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
139b0 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
139c0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
139d0 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
139e0 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
139f0 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
13a00 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
13a10 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
13a20 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
13a30 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
13a40 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13a50 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
13a60 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65  TOINIT] might be
13a70 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
13a80 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
13a90 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
13aa0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
13ab0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
13ac0 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
13ad0 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
13ae0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
13af0 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
13b00 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
13b10 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
13b20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
13b30 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
13b40 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
13b50 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
13b60 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
13b70 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
13b80 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
13b90 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
13ba0 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
13bb0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
13bc0 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
13bd0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
13be0 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
13bf0 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
13c00 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
13c10 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
13c20 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
13c30 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
13c40 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
13c50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13c60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
13c70 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
13c80 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
13c90 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
13ca0 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
13cb0 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
13cc0 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
13cd0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
13ce0 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
13cf0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
13d00 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
13d10 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
13d20 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
13d30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
13d40 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
13d50 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
13d60 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
13d70 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
13d80 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
13d90 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
13da0 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
13db0 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
13dc0 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
13dd0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
13de0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
13df0 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
13e00 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
13e10 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
13e20 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73  or Unix, Windows
13e30 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68  , or OS/2..** Wh
13e40 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64  en [custom build
13e50 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  s | built for ot
13e60 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a  her platforms].*
13e70 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51  * (using the [SQ
13e80 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d  LITE_OS_OTHER=1]
13e90 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
13ea0 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
13eb0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
13ec0 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
13ed0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
13ee0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
13ef0 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
13f00 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
13f10 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
13f20 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
13f30 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
13f40 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
13f50 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
13f60 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
13f70 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
13f80 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65  success and some
13f90 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f   other [error co
13fa0 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c  de] upon.** fail
13fb0 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ure..*/.SQLITE_A
13fc0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  PI int sqlite3_i
13fd0 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
13fe0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
13ff0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
14000 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
14010 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
14020 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51  s_init(void);.SQ
14030 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
14040 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
14050 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
14060 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
14070 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
14080 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
14090 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
140a0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
140b0 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
140c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
140d0 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
140e0 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
140f0 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
14100 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
14110 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
14120 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
14130 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
14140 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
14150 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
14160 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
14170 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
14180 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
14190 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
141a0 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
141b0 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
141c0 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
141d0 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
141e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
141f0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
14200 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
14210 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
14220 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
14230 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
14240 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
14250 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
14260 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
14270 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
14280 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
14290 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
142a0 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
142b0 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
142c0 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
142d0 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
142e0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
142f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
14300 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
14310 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
14320 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
14330 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
14340 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
14350 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
14360 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
14370 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
14380 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
14390 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
143a0 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
143b0 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
143c0 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
143d0 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
143e0 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
143f0 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
14400 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
14410 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
14420 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
14430 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
14440 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
14450 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
14460 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14470 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
14480 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
14490 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
144a0 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
144b0 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
144c0 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
144d0 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
144e0 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
144f0 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
14500 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
14510 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
14520 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
14530 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
14540 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
14550 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
14560 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
14570 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
14580 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
14590 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
145a0 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
145b0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
145c0 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
145d0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
145e0 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
145f0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
14600 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
14610 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e   int sqlite3_con
14620 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
14630 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14640 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
14650 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
14660 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
14670 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
14680 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
14690 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
146a0 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
146b0 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
146c0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
146d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
146e0 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
146f0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
14700 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
14710 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
14720 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
14730 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14740 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
14750 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
14760 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
14770 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
14780 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
14790 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
147a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
147b0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
147c0 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
147d0 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
147e0 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
147f0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
14800 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
14810 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14820 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
14830 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
14840 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
14850 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
14860 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
14870 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
14880 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
14890 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
148a0 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
148b0 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
148c0 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
148d0 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
148e0 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  essful..*/.SQLIT
148f0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
14900 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
14910 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
14920 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
14930 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
14940 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
14950 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
14960 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
14970 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
14980 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
14990 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
149a0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
149b0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
149c0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
149d0 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
149e0 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
149f0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
14a00 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
14a10 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
14a20 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
14a30 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
14a40 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
14a50 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
14a60 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
14a70 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
14a80 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
14a90 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
14aa0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
14ab0 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
14ac0 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
14ad0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
14ae0 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
14af0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
14b00 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
14b10 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
14b20 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
14b30 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
14b40 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
14b50 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
14b60 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
14b70 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
14b80 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
14b90 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
14ba0 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
14bb0 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
14bc0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
14bd0 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
14be0 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
14bf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
14c00 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
14c10 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
14c20 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
14c30 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
14c40 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
14c50 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
14c60 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
14c70 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
14c80 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
14c90 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
14ca0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
14cb0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
14cc0 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
14cd0 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
14ce0 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
14cf0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
14d00 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
14d10 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
14d20 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
14d30 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
14d40 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
14d50 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
14d60 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
14d70 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
14d80 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
14d90 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
14da0 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
14db0 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
14dc0 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
14dd0 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
14de0 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
14df0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
14e00 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
14e10 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
14e20 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
14e30 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
14e40 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
14e50 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
14e60 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
14e70 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
14e80 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
14e90 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
14ea0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
14eb0 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
14ec0 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
14ed0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
14ee0 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
14ef0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
14f00 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
14f10 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
14f20 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
14f30 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
14f40 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
14f50 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
14f60 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
14f70 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
14f80 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
14f90 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
14fa0 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
14fb0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
14fc0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
14fd0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
14fe0 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
14ff0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
15000 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
15010 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
15020 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
15030 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
15040 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
15050 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
15060 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
15070 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
15080 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
15090 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
150a0 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
150b0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
150c0 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
150d0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
150e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
150f0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
15100 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
15110 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
15120 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
15130 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
15140 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
15150 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
15160 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
15170 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
15180 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
15190 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
151a0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
151b0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
151c0 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
151d0 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
151e0 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
151f0 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
15200 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
15210 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
15220 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
15230 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
15240 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
15250 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
15260 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
15270 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
15280 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
15290 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
152a0 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
152b0 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
152c0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
152d0 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
152e0 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
152f0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
15300 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
15310 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
15320 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
15330 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
15340 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
15350 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
15360 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
15370 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
15380 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
15390 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
153a0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
153b0 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
153c0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
153d0 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
153e0 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
153f0 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
15400 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
15410 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
15420 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
15430 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
15440 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
15450 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
15460 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
15470 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
15480 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
15490 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
154a0 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
154b0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
154c0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
154d0 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
154e0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
154f0 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
15500 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
15510 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
15520 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
15530 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
15540 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
15550 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
15560 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
15570 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
15580 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
15590 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
155a0 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
155b0 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
155c0 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
155d0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
155e0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
155f0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
15600 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
15610 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
15620 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
15630 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
15640 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
15650 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
15660 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
15670 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
15680 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
15690 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
156a0 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
156b0 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
156c0 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
156d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
156e0 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
156f0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
15700 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
15710 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
15720 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
15730 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
15740 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
15750 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
15760 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
15770 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
15780 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
15790 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
157a0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
157b0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
157c0 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
157d0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
157e0 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
157f0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
15800 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
15810 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
15820 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
15830 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
15840 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
15850 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
15860 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
15870 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
15880 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
15890 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
158a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
158b0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
158c0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
158d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
158e0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
158f0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
15900 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15910 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
15920 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
15930 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
15940 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15950 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
15960 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
15970 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
15980 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
15990 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
159a0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
159b0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
159c0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
159d0 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
159e0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
159f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15a00 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
15a10 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
15a20 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
15a30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
15a40 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
15a50 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
15a60 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
15a70 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
15a80 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
15a90 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15aa0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
15ab0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
15ac0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15ad0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
15ae0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15af0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
15b00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
15b10 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
15b20 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
15b30 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
15b40 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
15b50 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
15b60 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
15b70 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
15b80 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
15b90 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
15ba0 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
15bb0 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
15bc0 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
15bd0 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
15be0 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
15bf0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
15c00 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
15c10 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15c20 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
15c30 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
15c40 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
15c50 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
15c60 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
15c70 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
15c80 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
15c90 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
15ca0 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
15cb0 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
15cc0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
15cd0 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
15ce0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
15cf0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
15d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
15d10 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
15d20 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15d30 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
15d40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15d50 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
15d60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15d70 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
15d80 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
15d90 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
15da0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
15db0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
15dc0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
15dd0 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
15de0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
15df0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
15e00 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
15e10 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
15e20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
15e30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
15e40 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
15e50 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
15e60 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
15e70 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
15e80 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
15e90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15ea0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
15eb0 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
15ec0 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
15ed0 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
15ee0 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
15ef0 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
15f00 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
15f10 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
15f20 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
15f30 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
15f40 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
15f50 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
15f60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15f70 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
15f80 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
15f90 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
15fa0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
15fb0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
15fc0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
15fd0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
15fe0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
15ff0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
16000 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
16010 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
16020 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
16030 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
16040 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
16050 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
16060 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
16070 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
16080 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
16090 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
160a0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
160b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
160c0 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
160d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
160e0 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
160f0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
16100 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
16110 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
16120 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
16130 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
16140 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
16150 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
16160 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
16170 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
16180 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
16190 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
161a0 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
161b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
161c0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
161d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
161e0 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
161f0 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
16200 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
16210 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
16220 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
16230 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
16240 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
16250 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
16260 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
16270 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
16280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
16290 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
162a0 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
162b0 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
162c0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
162d0 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
162e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
162f0 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
16300 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
16310 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
16320 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
16330 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
16340 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
16350 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
16360 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
16370 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
16380 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
16390 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
163a0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
163b0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
163c0 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
163d0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
163e0 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
163f0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
16400 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
16410 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
16420 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
16430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
16440 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
16450 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
16460 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16470 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
16480 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16490 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
164a0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
164b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
164c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
164d0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
164e0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
164f0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
16500 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
16510 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
16520 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
16530 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
16540 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
16550 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
16560 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
16570 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
16580 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
16590 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
165a0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
165b0 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
165c0 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
165d0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
165e0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
165f0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
16600 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
16610 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
16620 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
16630 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
16640 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16660 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
16670 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
16680 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
16690 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
166a0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
166b0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
166c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
166d0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
166e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
166f0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
16700 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
16710 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
16720 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
16730 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
16740 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
16750 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16760 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
16770 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
16780 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
16790 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
167a0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
167b0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
167c0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
167d0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
167e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
167f0 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
16800 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
16810 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
16820 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
16830 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
16840 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
16850 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
16860 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
16870 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
16880 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
16890 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
168a0 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
168b0 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
168c0 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
168d0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
168e0 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
168f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
16900 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  ** statistics. ^
16910 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
16920 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
16930 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c  cs are disabled,
16940 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69   the .** followi
16950 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
16960 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
16970 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
16980 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
16990 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
169a0 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
169b0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
169c0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
169d0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
169e0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
169f0 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
16a00 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
16a10 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  s()].**   </ul>)
16a20 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
16a30 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
16a40 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
16a50 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
16a60 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
16a70 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
16a80 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
16a90 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
16aa0 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
16ab0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
16ac0 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
16ad0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
16ae0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
16af0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
16b00 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
16b10 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
16b20 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
16b30 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
16b40 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
16b50 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
16b60 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
16b70 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
16b80 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
16b90 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
16ba0 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
16bb0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
16bc0 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
16bd0 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
16be0 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
16bf0 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
16c00 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
16c10 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
16c20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
16c30 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
16c40 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
16c50 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
16c60 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
16c70 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
16c80 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
16c90 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72  f 16..** The fir
16ca0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
16cb0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
16cc0 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
16cd0 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
16ce0 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
16cf0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
16d00 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
16d10 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
16d20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66  two scratch buff
16d30 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20  ers per thread. 
16d40 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
16d50 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20  be set to twice 
16d60 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
16d70 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
16d80 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69  hreads..** ^SQLi
16d90 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
16da0 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
16db0 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
16dc0 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
16dd0 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
16de0 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
16df0 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
16e00 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
16e10 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
16e20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
16e30 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
16e40 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16e50 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
16e60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16e70 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
16e80 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
16e90 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
16ea0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16eb0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
16ec0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16ed0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
16ee0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
16ef0 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
16f00 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
16f10 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
16f20 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
16f30 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
16f40 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
16f50 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
16f60 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
16f70 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
16f80 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
16f90 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
16fa0 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
16fb0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
16fc0 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
16fd0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
16fe0 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
16ff0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17000 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  HE2 option..** T
17010 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
17020 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
17030 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
17040 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69  er to 8-byte ali
17050 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
17060 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
17070 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
17080 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
17090 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
170a0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
170b0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
170c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
170d0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
170e0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
170f0 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
17100 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75  2 and 32768) plu
17110 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61  s a little extra
17120 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
17130 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
17140 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65  page header size
17150 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74   is 20 to 40 byt
17160 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a  es depending on.
17170 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68  ** the host arch
17180 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69  itecture.  ^It i
17190 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
171a0 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
171b0 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20  d memory,.** to 
171c0 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65  make sz a little
171d0 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65   too large.  The
171e0 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
171f0 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
17200 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
17210 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
17220 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
17230 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
17240 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
17250 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
17260 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17270 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
17280 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
17290 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
172a0 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
172b0 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
172c0 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
172d0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
172e0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
172f0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
17300 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
17310 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
17320 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
17330 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
17340 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
17350 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
17360 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  ** The pointer i
17370 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
17380 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
17390 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
173a0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
173b0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
173c0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
173d0 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
173e0 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
173f0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17400 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
17410 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
17420 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
17430 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
17440 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
17450 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
17460 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
17470 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
17480 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
17490 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
174a0 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
174b0 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
174c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
174d0 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
174e0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
174f0 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
17500 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
17510 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
17520 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
17530 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
17540 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
17550 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
17560 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
17570 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
17580 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
17590 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
175a0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
175b0 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
175c0 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
175d0 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
175e0 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
175f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
17600 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
17610 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
17620 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
17630 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
17640 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
17650 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
17660 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
17670 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
17680 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68  ot NULL and eith
17690 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
176a0 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a  E_MEMSYS3] or.**
176b0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
176c0 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66  MEMSYS5] are def
176d0 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61  ined, then the a
176e0 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
176f0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
17700 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
17710 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
17720 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
17730 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
17740 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
17750 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
17760 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
17770 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
17780 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
17790 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
177a0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
177b0 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
177c0 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
177d0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
177e0 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
177f0 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
17800 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
17810 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
17820 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
17830 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
17840 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
17850 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
17860 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
17870 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
17880 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
17890 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
178a0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
178b0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
178c0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
178d0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
178e0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
178f0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
17900 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
17910 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
17920 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
17930 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
17940 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
17950 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
17960 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
17970 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
17980 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
17990 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
179a0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
179b0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
179c0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
179d0 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
179e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
179f0 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
17a00 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
17a10 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
17a20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
17a30 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
17a40 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
17a50 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
17a60 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
17a70 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
17a80 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
17a90 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
17aa0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
17ab0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
17ac0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
17ad0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
17ae0 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
17af0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
17b00 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
17b10 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
17b20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17b30 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
17b40 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
17b50 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
17b60 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
17b70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17b80 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
17b90 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
17ba0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
17bb0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
17bc0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
17bd0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
17be0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
17bf0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
17c00 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
17c10 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
17c20 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
17c30 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
17c40 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
17c50 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
17c60 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
17c70 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
17c80 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
17c90 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
17ca0 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
17cb0 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
17cc0 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
17cd0 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
17ce0 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
17cf0 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
17d00 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
17d10 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
17d20 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
17d30 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
17d40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17d50 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
17d60 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
17d70 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
17d80 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
17d90 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
17da0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
17db0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
17dc0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
17dd0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
17de0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17df0 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
17e00 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
17e10 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
17e20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17e30 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
17e40 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17e50 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
17e60 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
17e70 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
17e80 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
17e90 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
17ea0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
17eb0 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
17ec0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
17ed0 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
17ee0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
17ef0 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
17f00 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
17f10 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
17f20 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
17f30 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
17f40 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
17f50 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
17f60 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
17f70 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
17f80 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
17f90 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
17fa0 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
17fb0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
17fc0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
17fd0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
17fe0 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
17ff0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
18000 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
18010 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
18020 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
18030 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
18040 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
18050 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
18060 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
18070 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c  NFIG_PCACHE2]] <
18080 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
18090 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  _PCACHE2</dt>.**
180a0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
180b0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
180c0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
180d0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
180e0 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33  o.** an [sqlite3
180f0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
18100 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
18110 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
18120 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
18130 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
18140 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
18150 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c  ntation.)^  ^SQL
18160 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
18170 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
18180 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
18190 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
181a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
181b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
181c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
181d0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
181e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
181f0 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
18200 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
18210 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
18220 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
18230 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
18240 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
18250 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
18260 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
18270 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72  opies of the cur
18280 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63  rent.** page cac
18290 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
182a0 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
182b0 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
182c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
182d0 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
182e0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
182f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
18300 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
18310 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
18320 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
18330 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
18340 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
18350 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
18360 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
18370 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
18380 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
18390 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
183a0 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
183b0 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
183c0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
183d0 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
183e0 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
183f0 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
18400 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
18410 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
18420 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
18430 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
18440 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
18450 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
18460 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
18470 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
18480 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
18490 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
184a0 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
184b0 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
184c0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
184d0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
184e0 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
184f0 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
18500 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
18510 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
18520 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
18530 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
18540 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
18550 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
18560 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
18570 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
18580 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
18590 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
185a0 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
185b0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
185c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
185d0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
185e0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
185f0 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
18600 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
18610 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
18620 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
18630 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
18640 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
18650 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
18660 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
18670 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
18680 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
18690 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
186a0 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
186b0 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
186c0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
186d0 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
186e0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
186f0 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
18700 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
18710 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
18720 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
18730 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
18740 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
18750 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
18760 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
18770 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
18780 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
18790 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
187a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
187b0 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
187c0 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
187d0 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  > This option ta
187e0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
187f0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
18800 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  t. If non-zero, 
18810 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64  then.** URI hand
18820 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
18830 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
18840 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
18850 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
18860 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62  dling.** is glob
18870 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49  ally disabled. I
18880 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
18890 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
188a0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
188b0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b  s.** passed to [
188c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
188d0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
188e0 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  2()], [sqlite3_o
188f0 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
18900 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
18910 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
18920 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
18930 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
18940 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
18950 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
18960 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
18970 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
18980 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
18990 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
189a0 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69   is opened. If i
189b0 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
189c0 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
189d0 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
189e0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
189f0 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
18a00 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
18a10 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
18a20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18a30 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
18a40 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
18a50 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
18a60 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
18a70 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
18a80 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
18a90 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
18aa0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
18ab0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
18ac0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  bol defined..**.
18ad0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
18ae0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
18af0 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c  X_SCAN]] <dt>SQL
18b00 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
18b10 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a  ING_INDEX_SCAN.*
18b20 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69  * <dd> This opti
18b30 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
18b40 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d 65  e integer argume
18b50 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
18b60 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61 20  rpreted as.** a 
18b70 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
18b80 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
18b90 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
18ba0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
18bb0 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61  s for.** full ta
18bc0 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
18bd0 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
18be0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 73  .  The default s
18bf0 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
18c00 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
18c10 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
18c20 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
18c30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
18c40 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
18c50 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
18c60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
18c70 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
18c80 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
18c90 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
18ca0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
18cb0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
18cc0 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
18cd0 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
18ce0 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
18cf0 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
18d00 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
18d10 6f 6e 0a 2a 2a 20 6d 61 6c 66 75 6e 63 74 69 6f  on.** malfunctio
18d20 6e 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  n when the optim
18d30 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
18d40 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
18d50 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
18d60 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
18d70 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
18d80 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
18d90 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
18da0 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
18db0 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
18dc0 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
18dd0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
18de0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
18df0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
18e00 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
18e10 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
18e20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
18e30 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
18e40 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
18e50 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
18e60 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
18e70 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
18e80 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
18e90 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
18ea0 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
18eb0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
18ec0 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
18ed0 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
18ee0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
18ef0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
18f00 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
18f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
18f20 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
18f30 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
18f40 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
18f50 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
18f60 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
18f70 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
18f80 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
18f90 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
18fa0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18fb0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
18fc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
18fd0 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
18fe0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
18ff0 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
19000 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
19010 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
19020 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
19030 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
19040 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
19050 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
19060 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
19070 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
19080 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
19090 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
190a0 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
190b0 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
190c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
190d0 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
190e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
190f0 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
19100 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
19110 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
19120 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
19130 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
19140 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
19150 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
19160 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
19170 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
19180 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
19190 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
191a0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
191b0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
191c0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
191d0 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
191e0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
191f0 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
19200 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
19210 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
19220 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
19230 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
19240 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
19250 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
19260 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
19270 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
19280 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
19290 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
192a0 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
192b0 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
192c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
192d0 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
192e0 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
192f0 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
19300 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
19310 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
19320 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
19330 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
19340 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
19350 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
19360 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
19370 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
19380 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74  MAP_SIZE takes t
19390 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  wo 64-bit intege
193a0 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  r (sqlite3_int64
193b0 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  ) values.** that
193c0 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74   are the default
193d0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
193e0 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65   (the default se
193f0 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52  tting for.** [PR
19400 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29  AGMA mmap_size])
19410 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
19420 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
19430 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 54 68 65  ze limit..** The
19440 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
19450 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
19460 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62  en by each datab
19470 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75  ase connection u
19480 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74  sing.** either t
19490 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  he [PRAGMA mmap_
194a0 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f  size] command, o
194b0 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a  r by using the.*
194c0 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
194d0 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
194e0 63 6f 6e 74 72 6f 6c 2e 20 20 54 68 65 20 6d 61  control.  The ma
194f0 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
19500 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f  ap size.** canno
19510 74 20 62 65 20 63 68 61 6e 67 65 64 20 61 74 20  t be changed at 
19520 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20 6d  run-time.  Nor m
19530 61 79 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  ay the maximum a
19540 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
19550 0a 2a 2a 20 65 78 63 65 65 64 20 74 68 65 20 63  .** exceed the c
19560 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69  ompile-time maxi
19570 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65  mum mmap size se
19580 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
19590 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a  ITE_MAX_MMAP_SIZ
195a0 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
195b0 6f 70 74 69 6f 6e 2e 20 20 0a 2a 2a 20 49 66 20  option.  .** If 
195c0 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
195d0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
195e0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
195f0 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
19600 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
19610 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
19620 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
19630 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
19640 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
19650 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
19660 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
19670 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
19680 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
19690 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
196a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
196b0 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
196c0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
196d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
196e0 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
196f0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
19700 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
19710 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
19720 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
19730 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
19740 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
19750 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19760 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
19770 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
19780 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
19790 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
197a0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
197b0 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
197c0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
197d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
197e0 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
197f0 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
19800 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
19810 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
19820 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
19830 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
19840 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
19850 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19860 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
19870 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
19880 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
19890 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
198a0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
198b0 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
198c0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
198d0 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
198e0 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
198f0 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
19900 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
19910 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
19920 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
19930 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
19940 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
19950 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19960 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
19970 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  14  /* no-op */.
19980 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19990 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
199a0 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20     15  /* no-op 
199b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
199c0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
199d0 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
199e0 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  nc, void* */.#de
199f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19a00 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  IG_URI          
19a10 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  17  /* int */.#d
19a20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
19a30 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20  FIG_PCACHE2     
19a40 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   18  /* sqlite3_
19a50 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
19a60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19a70 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
19a80 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71  CHE2   19  /* sq
19a90 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
19aa0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
19ab0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19ac0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
19ad0 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a  CAN 20  /* int *
19ae0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19af0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20  _CONFIG_SQLLOG  
19b00 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c       21  /* xSql
19b10 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  log, void* */.#d
19b20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
19b30 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  FIG_MMAP_SIZE   
19b40 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   22  /* sqlite3_
19b50 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69  int64, sqlite3_i
19b60 6e 74 36 34 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  nt64 */../*.** C
19b70 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
19b80 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
19b90 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
19ba0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
19bb0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
19bc0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
19bd0 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
19be0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
19bf0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
19c00 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
19c10 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
19c20 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
19c30 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
19c40 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
19c50 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
19c60 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
19c70 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
19c80 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
19c90 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
19ca0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
19cb0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
19cc0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
19cd0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
19ce0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
19cf0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
19d00 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
19d10 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
19d20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
19d30 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
19d40 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
19d50 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
19d60 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
19d70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
19d80 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
19d90 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
19da0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
19db0 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
19dc0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
19dd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19de0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
19df0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
19e00 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
19e10 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
19e20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
19e30 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
19e40 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
19e50 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
19e60 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
19e70 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
19e80 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
19e90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19ea0 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
19eb0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
19ec0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
19ed0 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
19ee0 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
19ef0 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
19f00 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
19f10 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
19f20 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
19f30 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19f40 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
19f50 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
19f60 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
19f70 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
19f80 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
19f90 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
19fa0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
19fb0 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
19fc0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
19fd0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
19fe0 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
19ff0 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
1a000 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
1a010 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
1a020 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
1a030 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
1a040 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
1a050 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
1a060 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
1a070 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
1a080 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
1a090 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
1a0a0 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
1a0b0 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
1a0c0 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
1a0d0 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
1a0e0 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
1a0f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
1a100 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
1a110 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
1a120 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
1a130 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
1a140 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
1a150 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
1a160 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
1a170 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
1a180 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
1a190 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
1a1a0 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
1a1b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
1a1c0 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
1a1d0 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
1a1e0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
1a1f0 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
1a200 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
1a210 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
1a220 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
1a230 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
1a240 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
1a250 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
1a260 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
1a270 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
1a280 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
1a290 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
1a2a0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
1a2b0 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
1a2c0 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
1a2d0 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
1a2e0 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
1a2f0 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
1a300 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
1a310 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
1a320 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
1a330 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1a340 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1a350 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
1a360 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
1a370 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
1a380 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
1a390 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
1a3a0 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
1a3b0 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
1a3c0 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
1a3d0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
1a3e0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
1a3f0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1a400 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
1a410 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
1a420 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
1a430 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
1a440 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
1a450 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
1a460 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
1a470 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
1a480 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
1a490 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1a4a0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
1a4b0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
1a4c0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
1a4d0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
1a4e0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
1a4f0 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
1a500 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
1a510 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
1a520 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
1a530 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
1a540 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
1a550 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
1a560 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
1a570 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
1a580 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
1a590 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
1a5a0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
1a5b0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
1a5c0 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
1a5d0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
1a5e0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
1a5f0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
1a600 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
1a610 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
1a620 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
1a630 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
1a640 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
1a650 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
1a660 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
1a670 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
1a680 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
1a690 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
1a6a0 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
1a6b0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
1a6c0 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
1a6d0 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
1a6e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1a6f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
1a700 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
1a710 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
1a720 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
1a730 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
1a740 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
1a750 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
1a760 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
1a770 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
1a780 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
1a790 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
1a7a0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
1a7b0 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
1a7c0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
1a7d0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
1a7e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
1a7f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a800 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
1a810 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
1a820 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
1a830 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
1a840 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1a850 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
1a860 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
1a870 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a880 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1a890 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
1a8a0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
1a8b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a8c0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
1a8d0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
1a8e0 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
1a8f0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
1a900 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
1a910 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
1a920 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
1a930 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
1a940 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
1a950 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
1a960 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
1a970 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
1a980 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
1a990 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
1a9a0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
1a9b0 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lity..*/.SQLITE_
1a9c0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1a9d0 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
1a9e0 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
1a9f0 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
1aa00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
1aa10 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
1aa20 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
1aa30 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61   in an SQLite ta
1aa40 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65  ble has a unique
1aa50 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
1aa60 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
1aa70 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
1aa80 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
1aa90 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
1aaa0 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
1aab0 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
1aac0 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
1aad0 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
1aae0 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
1aaf0 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
1ab00 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
1ab10 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
1ab20 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
1ab30 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
1ab40 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
1ab50 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
1ab60 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
1ab70 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
1ab80 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
1ab90 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
1aba0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1abb0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ne returns the [
1abc0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f  rowid] of the mo
1abd0 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63  st recent.** suc
1abe0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
1abf0 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
1ac00 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74  se from the [dat
1ac10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ac20 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
1ac30 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73  t argument.  ^As
1ac40 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
1ac50 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72  on 3.7.7, this r
1ac60 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72  outines.** recor
1ac70 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  ds the last inse
1ac80 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68  rt rowid of both
1ac90 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73   ordinary tables
1aca0 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61   and [virtual ta
1acb0 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  bles]..** ^If no
1acc0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
1acd0 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
1ace0 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
1acf0 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
1ad00 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
1ad10 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1ad20 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
1ad30 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
1ad40 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74  a trigger or wit
1ad50 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74  hin a [virtual t
1ad60 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c  able].** method,
1ad70 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
1ad80 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74  ne will return t
1ad90 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
1ada0 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
1adb0 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  w as long as the
1adc0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
1add0 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
1ade0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
1adf0 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
1ae00 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
1ae10 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64  table method end
1ae20 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
1ae30 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
1ae40 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
1ae50 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
1ae60 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
1ae70 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a  ger or virtual.*
1ae80 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62  * table method b
1ae90 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  egan.)^.**.** ^A
1aea0 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
1aeb0 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
1aec0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
1aed0 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
1aee0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
1aef0 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
1af00 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
1af10 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
1af20 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
1af30 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
1af40 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
1af50 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
1af60 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
1af70 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
1af80 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
1af90 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
1afa0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
1afb0 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
1afc0 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
1afd0 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
1afe0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
1aff0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
1b000 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
1b010 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
1b020 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
1b030 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
1b040 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
1b050 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
1b060 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
1b070 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
1b080 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
1b090 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
1b0a0 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
1b0b0 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
1b0c0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
1b0d0 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
1b0e0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
1b0f0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
1b100 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
1b110 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
1b120 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
1b130 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
1b140 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
1b150 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
1b160 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
1b170 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
1b180 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
1b190 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
1b1a0 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
1b1b0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1b1c0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1b1d0 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
1b1e0 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
1b1f0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
1b200 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b210 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
1b220 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1b230 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
1b240 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
1b250 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
1b260 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
1b270 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
1b280 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
1b290 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1b2a0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1b2b0 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
1b2c0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
1b2d0 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
1b2e0 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
1b2f0 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
1b300 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
1b310 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
1b320 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1b330 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1b340 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
1b350 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b360 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
1b370 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
1b380 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
1b390 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1b3a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1b3b0 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
1b3c0 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
1b3d0 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  ** or inserted o
1b3e0 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
1b3f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
1b400 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61  ompleted SQL sta
1b410 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65  tement.** on the
1b420 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b430 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
1b440 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
1b450 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e  rameter..** ^(On
1b460 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
1b470 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
1b480 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
1b490 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
1b4a0 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
1b4b0 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
1b4c0 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
1b4d0 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
1b4e0 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
1b4f0 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   or [foreign key
1b500 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f   actions] are no
1b510 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65  t counted.)^ Use
1b520 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1b530 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1b540 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69  ] function to fi
1b550 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
1b560 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a  ber of changes.*
1b570 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  * including chan
1b580 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
1b590 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69  iggers and forei
1b5a0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a  gn key actions..
1b5b0 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74  **.** ^Changes t
1b5c0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
1b5d0 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61  e simulated by a
1b5e0 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
1b5f0 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f  igger].** are no
1b600 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79  t counted.  Only
1b610 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e   real table chan
1b620 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ges are counted.
1b630 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20  .**.** ^(A "row 
1b640 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
1b650 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
1b660 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
1b670 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
1b680 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
1b690 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
1b6a0 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
1b6b0 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
1b6c0 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
1b6d0 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45  ects of [REPLACE
1b6e0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
1b6f0 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
1b700 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
1b710 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41  essing, [DROP TA
1b720 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20  BLE], or by any 
1b730 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
1b740 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
1b750 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
1b760 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  hanges.)^.**.** 
1b770 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
1b780 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
1b790 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
1b7a0 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
1b7b0 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
1b7c0 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45  ipt of a [CREATE
1b7d0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
1b7e0 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51  er]. .** Most SQ
1b7f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
1b800 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
1b810 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
1b820 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
1b830 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
1b840 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
1b850 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
1b860 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
1b870 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
1b880 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
1b890 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
1b8a0 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
1b8b0 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
1b8c0 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
1b8d0 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
1b8e0 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
1b8f0 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
1b900 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  * ^Calling [sqli
1b910 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
1b920 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b930 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
1b940 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
1b950 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
1b960 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  text..**.** ^Thi
1b970 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1b980 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1b990 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
1b9a0 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
1b9b0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
1b9c0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
1b9d0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
1b9e0 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
1b9f0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
1ba00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77  ..**.** ^Thus, w
1ba10 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
1ba20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74  the top level, t
1ba30 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
1ba40 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
1ba50 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
1ba60 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1ba70 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
1ba80 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
1ba90 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64  at also occurred
1baa0 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65   at the top leve
1bab0 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65  l.  ^(Within the
1bac0 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
1bad0 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
1bae0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
1baf0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
1bb00 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
1bb10 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
1bb20 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
1bb30 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
1bb40 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
1bb50 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
1bb60 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
1bb70 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
1bb80 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
1bb90 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
1bba0 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
1bbb0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1bbc0 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
1bbd0 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
1bbe0 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
1bbf0 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
1bc00 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  ntext.)^.**.** S
1bc10 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1bc20 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1bc30 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
1bc40 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
1bc50 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
1bc60 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
1bc70 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1bc80 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1bc90 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1bca0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1bcb0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1bcc0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1bcd0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
1bce0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1bcf0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1bd00 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
1bd10 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1bd20 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1bd30 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
1bd40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61   int sqlite3_cha
1bd50 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1bd60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1bd70 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
1bd80 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
1bd90 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
1bda0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1bdb0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
1bdc0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
1bdd0 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
1bde0 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
1bdf0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
1be00 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
1be10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
1be20 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68   opened..** ^(Th
1be30 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64  e count returned
1be40 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
1be50 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c  l_changes() incl
1be60 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
1be70 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52  .** from all [CR
1be80 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
1be90 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73  rigger] contexts
1bea0 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64   and changes mad
1beb0 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  e by.** [foreign
1bec0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48   key actions]. H
1bed0 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
1bee0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
1bef0 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
1bf00 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1bf10 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
1bf20 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
1bf30 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
1bf40 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b  processing, or [
1bf50 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63  DROP TABLE] proc
1bf60 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20  essing.  The.** 
1bf70 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
1bf80 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76  nclude rows of v
1bf90 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61  iews that fire a
1bfa0 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
1bfb0 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67  igger],.** thoug
1bfc0 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44  h if the INSTEAD
1bfd0 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65   OF trigger make
1bfe0 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73  s changes of its
1bff0 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e   own, those chan
1c000 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  ges .** are coun
1c010 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73  ted.)^.** ^The s
1c020 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1c030 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
1c040 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67  counts the chang
1c050 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a  es as soon as.**
1c060 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
1c070 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
1c080 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65  s completed (whe
1c090 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
1c0a0 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73  handle.** is pas
1c0b0 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
1c0c0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
1c0d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1c0e0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
1c0f0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
1c100 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1c110 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
1c120 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1c130 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
1c140 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
1c150 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1c160 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1c170 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1c180 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1c190 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c1a0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1c1b0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1c1c0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1c1d0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1c1e0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
1c1f0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1c200 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1c210 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
1c220 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74   int sqlite3_tot
1c230 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
1c240 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1c250 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
1c260 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
1c270 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  Query.**.** ^Thi
1c280 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
1c290 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
1c2a0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1c2b0 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
1c2c0 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
1c2d0 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
1c2e0 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
1c2f0 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
1c300 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
1c310 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
1c320 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
1c330 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
1c340 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
1c350 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
1c360 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
1c370 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
1c380 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
1c390 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
1c3a0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1c3b0 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
1c3c0 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
1c3d0 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
1c3e0 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
1c3f0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
1c400 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
1c410 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
1c420 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
1c430 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
1c440 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1c450 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
1c460 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
1c470 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
1c480 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
1c490 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
1c4a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
1c4b0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1c4c0 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
1c4d0 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
1c4e0 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
1c4f0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
1c500 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
1c510 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
1c520 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
1c530 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
1c540 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
1c550 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
1c560 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
1c570 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
1c580 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
1c590 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
1c5a0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
1c5b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
1c5c0 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
1c5d0 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
1c5e0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
1c5f0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
1c600 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
1c610 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
1c620 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
1c630 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
1c640 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
1c650 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
1c660 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
1c670 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1c680 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
1c690 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
1c6a0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
1c6b0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1c6c0 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
1c6d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
1c6e0 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
1c6f0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
1c700 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1c710 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1c720 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1c730 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
1c740 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
1c750 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
1c760 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
1c770 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
1c780 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
1c790 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
1c7a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1c7b0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1c7c0 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
1c7d0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1c7e0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1c7f0 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
1c800 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
1c810 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
1c820 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
1c830 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1c840 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
1c850 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1c860 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
1c870 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
1c880 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
1c890 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
1c8a0 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
1c8b0 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
1c8c0 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
1c8d0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1c8e0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1c8f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1c900 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
1c910 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ns..**.** If the
1c920 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c930 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
1c940 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
1c950 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75  rupt()].** is ru
1c960 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
1c970 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
1c980 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c  y happen..*/.SQL
1c990 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1c9a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
1c9b0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1c9c0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
1c9d0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
1c9e0 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
1c9f0 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
1ca00 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
1ca10 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
1ca20 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
1ca30 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
1ca40 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
1ca50 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
1ca60 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
1ca70 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
1ca80 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
1ca90 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
1caa0 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
1cab0 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
1cac0 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
1cad0 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
1cae0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1caf0 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
1cb00 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
1cb10 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
1cb20 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
1cb30 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
1cb40 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
1cb50 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
1cb60 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
1cb70 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
1cb80 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
1cb90 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
1cba0 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
1cbb0 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
1cbc0 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
1cbd0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
1cbe0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
1cbf0 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
1cc00 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
1cc10 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
1cc20 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
1cc30 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
1cc40 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
1cc50 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
1cc60 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
1cc70 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
1cc80 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
1cc90 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
1cca0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
1ccb0 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
1ccc0 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
1ccd0 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
1cce0 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
1ccf0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
1cd00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1cd10 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
1cd20 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
1cd30 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
1cd40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1cd50 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
1cd60 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
1cd70 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
1cd80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
1cd90 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
1cda0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
1cdb0 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
1cdc0 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
1cdd0 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
1cde0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
1cdf0 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
1ce00 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
1ce10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
1ce20 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
1ce30 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
1ce40 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1ce50 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
1ce60 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
1ce70 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
1ce80 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
1ce90 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1cea0 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
1ceb0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
1cec0 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
1ced0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
1cee0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
1cef0 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
1cf00 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
1cf10 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1cf20 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
1cf30 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
1cf40 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
1cf50 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1cf60 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
1cf70 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
1cf80 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
1cf90 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
1cfa0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
1cfb0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1cfc0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1cfd0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1cfe0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
1cff0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1d000 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
1d010 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d   int sqlite3_com
1d020 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
1d030 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   *sql);.SQLITE_A
1d040 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
1d050 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
1d060 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
1d070 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
1d080 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
1d090 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
1d0a0 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
1d0b0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1d0c0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
1d0d0 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
1d0e0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1d0f0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
1d100 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
1d110 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
1d120 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e  se table that an
1d130 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
1d140 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
1d150 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ocked..**.** ^If
1d160 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1d170 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
1d180 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
1d190 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
1d1a0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
1d1b0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1d1c0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
1d1d0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
1d1e0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1d1f0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
1d200 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1d210 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
1d220 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
1d230 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
1d240 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
1d250 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
1d260 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
1d270 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
1d280 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
1d290 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
1d2a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1d2b0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1d2c0 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
1d2d0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
1d2e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1d2f0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1d300 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
1d310 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
1d320 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
1d330 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
1d340 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
1d350 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
1d360 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
1d370 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
1d380 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
1d390 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
1d3a0 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
1d3b0 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
1d3c0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
1d3d0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
1d3e0 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
1d3f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
1d400 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1d410 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
1d420 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
1d430 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
1d440 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
1d450 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
1d460 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
1d470 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
1d480 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
1d490 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
1d4a0 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
1d4b0 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
1d4c0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
1d4d0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
1d4e0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
1d4f0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
1d500 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
1d510 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
1d520 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
1d530 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
1d540 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
1d550 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1d560 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
1d570 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
1d580 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
1d590 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1d5a0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
1d5b0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
1d5c0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
1d5d0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
1d5e0 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
1d5f0 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
1d600 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
1d610 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
1d620 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
1d630 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
1d640 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
1d650 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
1d660 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
1d670 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
1d680 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1d690 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
1d6a0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
1d6b0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
1d6c0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
1d6d0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
1d6e0 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
1d6f0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1d700 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
1d710 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
1d720 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
1d730 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1d740 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
1d750 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
1d760 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
1d770 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
1d780 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
1d790 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
1d7a0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
1d7b0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
1d7c0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
1d7d0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
1d7e0 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
1d7f0 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
1d800 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1d810 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
1d820 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1d830 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1d840 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
1d850 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
1d860 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
1d870 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
1d880 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
1d890 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
1d8a0 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
1d8b0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
1d8c0 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
1d8d0 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
1d8e0 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
1d8f0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
1d900 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
1d910 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
1d920 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
1d930 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
1d940 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
1d950 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
1d960 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
1d970 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
1d980 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
1d990 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
1d9a0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
1d9b0 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
1d9c0 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
1d9d0 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66  ** readers.  ^If
1d9e0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
1d9f0 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
1da00 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
1da10 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
1da20 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
1da30 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
1da40 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
1da50 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
1da60 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
1da70 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
1da80 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
1da90 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
1daa0 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
1dab0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
1dac0 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f    ^This error co
1dad0 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
1dae0 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
1daf0 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
1db00 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
1db10 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
1db20 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
1db30 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
1db40 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
1db50 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
1db60 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
1db70 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
1db80 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
1db90 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
1dba0 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
1dbb0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1dbc0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1dbd0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
1dbe0 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
1dbf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1dc00 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
1dc10 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
1dc20 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
1dc30 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
1dc40 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
1dc50 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
1dc60 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1dc70 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
1dc80 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
1dc90 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
1dca0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
1dcb0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
1dcc0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
1dcd0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
1dce0 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
1dcf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1dd00 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1dd10 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
1dd20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
1dd30 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
1dd40 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
1dd50 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
1dd60 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
1dd70 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
1dd80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1dd90 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
1dda0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1ddb0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1ddc0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c   handler..*/.SQL
1ddd0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1dde0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1ddf0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
1de00 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
1de10 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1de20 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1de30 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20  y Timeout.**.** 
1de40 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
1de50 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
1de60 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
1de70 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
1de80 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
1de90 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
1dea0 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
1deb0 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
1dec0 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
1ded0 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
1dee0 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
1def0 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
1df00 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1df10 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
1df20 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
1df30 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
1df40 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1df50 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
1df60 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
1df70 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
1df80 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
1df90 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
1dfa0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
1dfb0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
1dfc0 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
1dfd0 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
1dfe0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
1dff0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
1e000 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
1e010 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
1e020 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
1e030 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
1e040 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1e050 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1e060 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
1e070 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1e080 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
1e090 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1e0a0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1e0b0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1e0c0 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1e0d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1e0e0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1e0f0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1e100 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1e110 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1e120 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1e130 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  d.)^.*/.SQLITE_A
1e140 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
1e150 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
1e160 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
1e170 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e180 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
1e190 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
1e1a0 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54   Queries.**.** T
1e1b0 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1e1c0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1e1d0 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1e1e0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1e1f0 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1e200 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1e210 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1e220 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1e230 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1e240 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1e250 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1e260 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1e270 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1e280 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1e290 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1e2a0 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1e2b0 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1e2c0 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1e2d0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1e2e0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1e2f0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1e300 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1e310 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1e320 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1e330 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1e340 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1e350 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1e360 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1e370 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1e380 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1e390 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1e3a0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1e3b0 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1e3c0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1e3d0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1e3e0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1e3f0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1e400 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1e410 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1e420 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1e430 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1e440 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1e450 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1e460 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1e470 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1e480 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1e490 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1e4a0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1e4b0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1e4c0 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1e4d0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1e4e0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1e4f0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1e500 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1e510 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1e520 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1e530 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1e540 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1e550 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1e560 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1e570 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1e580 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1e590 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1e5a0 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1e5b0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1e5c0 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1e5d0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1e5e0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1e5f0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1e600 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1e610 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1e620 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1e630 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1e640 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1e650 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1e660 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1e670 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1e680 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1e690 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1e6a0 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1e6b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e6c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1e6d0 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1e6e0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1e6f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1e700 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1e710 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1e720 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1e730 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1e740 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1e750 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1e760 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1e770 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1e780 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1e790 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1e7a0 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1e7b0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1e7c0 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1e7d0 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1e7e0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1e7f0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1e800 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1e810 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1e820 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1e830 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1e840 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e850 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1e860 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1e870 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1e880 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1e890 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1e8a0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1e8b0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1e8c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1e8d0 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1e8e0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1e8f0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1e900 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1e910 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1e920 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1e930 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1e940 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1e950 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1e960 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1e970 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1e980 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1e990 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1e9a0 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1e9b0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1e9c0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1e9d0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1e9e0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1e9f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1ea00 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1ea10 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1ea20 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1ea30 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1ea40 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1ea50 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1ea60 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1ea70 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1ea80 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1ea90 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1eaa0 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1eab0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1eac0 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1ead0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1eae0 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1eaf0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1eb00 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1eb10 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1eb20 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1eb30 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1eb40 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1eb50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1eb60 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1eb70 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1eb80 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1eb90 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1eba0 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1ebb0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1ebc0 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1ebd0 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1ebe0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1ebf0 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1ec00 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1ec10 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1ec20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1ec30 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1ec40 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1ec50 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1ec60 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1ec70 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1ec80 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1ec90 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1eca0 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1ecb0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1ecc0 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1ecd0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1ece0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1ecf0 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1ed00 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1ed10 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1ed20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1ed30 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1ed40 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1ed50 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1ed60 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1ed70 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1ed80 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1ed90 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1eda0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1edb0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1edc0 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1edd0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1ede0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1edf0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1ee00 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1ee10 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1ee20 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1ee30 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1ee40 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1ee50 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1ee60 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1ee70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1ee80 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1ee90 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1eea0 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1eeb0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1eec0 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1eed0 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1eee0 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1eef0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1ef00 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1ef10 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1ef20 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1ef30 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1ef40 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1ef50 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
1ef60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1ef70 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
1ef80 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
1ef90 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
1efa0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
1efb0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1efc0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1efd0 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
1efe0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
1eff0 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
1f000 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
1f010 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1f020 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ibrary..**.** ^T
1f030 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1f040 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1f050 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1f060 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1f070 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1f080 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1f090 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1f0a0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
1f0b0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1f0c0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
1f0d0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
1f0e0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
1f0f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f100 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
1f110 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
1f120 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
1f130 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f140 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
1f150 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
1f160 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
1f170 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
1f180 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
1f190 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
1f1a0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1f1b0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
1f1c0 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
1f1d0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1f1e0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
1f1f0 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
1f200 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
1f210 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
1f220 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1f230 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
1f240 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
1f250 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1f260 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
1f270 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
1f280 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
1f290 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
1f2a0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
1f2b0 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
1f2c0 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
1f2d0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
1f2e0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
1f2f0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
1f300 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1f310 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
1f320 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
1f330 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1f340 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
1f350 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
1f360 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1f370 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
1f380 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
1f390 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
1f3a0 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
1f3b0 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
1f3c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1f3d0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
1f3e0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
1f3f0 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
1f400 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
1f410 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
1f420 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1f430 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1f440 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
1f450 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
1f460 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
1f470 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
1f480 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
1f490 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
1f4a0 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
1f4b0 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
1f4c0 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
1f4d0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
1f4e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
1f4f0 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
1f500 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
1f510 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
1f520 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
1f530 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
1f540 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
1f550 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
1f560 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
1f570 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
1f580 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
1f590 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
1f5a0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
1f5b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
1f5c0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1f5d0 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
1f5e0 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
1f5f0 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
1f600 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1f610 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
1f620 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1f630 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
1f640 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
1f650 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
1f660 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
1f670 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
1f680 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
1f690 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
1f6a0 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
1f6b0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
1f6c0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
1f6d0 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
1f6e0 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
1f6f0 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
1f700 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
1f710 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
1f720 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d  tutes a nul-term
1f730 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1f740 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
1f750 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
1f760 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
1f770 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
1f780 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
1f790 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
1f7a0 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
1f7b0 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
1f7c0 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
1f7d0 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
1f7e0 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
1f7f0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
1f800 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
1f810 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
1f820 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
1f830 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
1f840 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
1f850 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
1f860 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
1f870 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1f880 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1f890 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
1f8a0 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
1f8b0 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
1f8c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1f8d0 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
1f8e0 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
1f8f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
1f900 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1f910 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1f920 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1f930 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1f940 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1f950 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
1f960 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1f970 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1f980 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1f990 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1f9a0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1f9b0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1f9c0 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
1f9d0 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
1f9e0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
1f9f0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
1fa00 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
1fa10 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
1fa20 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
1fa30 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1fa40 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1fa50 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1fa60 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1fa70 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
1fa80 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
1fa90 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1faa0 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
1fab0 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
1fac0 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
1fad0 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
1fae0 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
1faf0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
1fb00 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
1fb10 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1fb20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1fb30 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
1fb40 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
1fb50 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1fb60 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1fb70 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
1fb80 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
1fb90 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
1fba0 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
1fbb0 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
1fbc0 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
1fbd0 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
1fbe0 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
1fbf0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1fc00 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
1fc10 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1fc20 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
1fc30 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
1fc40 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
1fc50 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
1fc60 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
1fc70 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
1fc80 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
1fc90 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
1fca0 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
1fcb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
1fcc0 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
1fcd0 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
1fce0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
1fcf0 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
1fd00 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
1fd10 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
1fd20 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1fd30 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1fd40 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1fd50 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1fd60 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
1fd70 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
1fd80 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1fd90 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1fda0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1fdb0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1fdc0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1fdd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
1fde0 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
1fdf0 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
1fe00 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1fe10 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
1fe20 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
1fe30 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
1fe40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1fe50 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
1fe60 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1fe70 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
1fe80 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
1fe90 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
1fea0 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
1feb0 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
1fec0 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
1fed0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
1fee0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1fef0 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
1ff00 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
1ff10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
1ff20 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
1ff30 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1ff40 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,...);.SQLITE_AP
1ff50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1ff60 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
1ff70 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1ff80 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1ff90 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
1ffa0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1ffb0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53  t char*, ...);.S
1ffc0 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1ffd0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1ffe0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1fff0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
20000 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20010 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
20020 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
20030 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
20040 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
20050 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
20060 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
20070 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
20080 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
20090 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
200a0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
200b0 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
200c0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
200d0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
200e0 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
200f0 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
20100 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
20110 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
20120 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
20130 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
20140 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
20150 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
20160 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
20170 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
20180 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
20190 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
201a0 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
201b0 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
201c0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
201d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
201e0 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
201f0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
20200 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
20210 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
20220 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
20230 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
20240 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
20250 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
20260 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
20270 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
20280 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
20290 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
202a0 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
202b0 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
202c0 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
202d0 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
202e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
202f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
20300 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
20310 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
20320 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
20330 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
20340 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
20350 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
20360 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
20370 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
20380 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
20390 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
203a0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
203b0 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
203c0 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
203d0 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
203e0 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
203f0 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
20400 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
20410 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
20420 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
20430 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
20440 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
20450 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
20460 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
20470 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
20480 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
20490 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
204a0 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
204b0 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
204c0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
204d0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
204e0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
204f0 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
20500 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
20510 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
20520 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20530 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ()..**.** ^(The 
20540 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20550 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
20560 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
20570 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
20580 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
20590 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
205a0 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
205b0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
205c0 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
205d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
205e0 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
205f0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
20600 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74  ameter.)^ ^ If t
20610 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
20620 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
20630 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
20640 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
20650 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
20660 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
20670 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
20680 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
20690 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
206a0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
206b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
206c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63  ..** ^If the sec
206d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
206e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
206f0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
20700 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
20710 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
20720 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
20730 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
20740 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
20750 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
20760 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
20770 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20780 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
20790 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
207a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
207b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
207c0 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
207d0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
207e0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
207f0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
20800 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
20810 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
20820 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
20830 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
20840 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
20850 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
20860 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
20870 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
20880 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
20890 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
208a0 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
208b0 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
208c0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
208d0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
208e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
208f0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
20900 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
20910 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
20920 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
20930 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
20940 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
20950 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
20960 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
20970 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
20980 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
20990 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
209a0 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
209b0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
209c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
209d0 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
209e0 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
209f0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
20a00 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
20a10 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
20a20 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
20a30 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
20a40 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
20a50 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
20a60 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
20a70 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
20a80 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
20a90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
20aa0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
20ab0 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
20ac0 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
20ad0 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
20ae0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
20af0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
20b00 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
20b10 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
20b20 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
20b30 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
20b40 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
20b50 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
20b60 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
20b70 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
20b80 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
20b90 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
20ba0 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
20bb0 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
20bc0 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
20bd0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
20be0 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
20bf0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
20c00 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
20c10 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
20c20 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
20c30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
20c40 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
20c50 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
20c60 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
20c70 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
20c80 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
20c90 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
20ca0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
20cb0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
20cc0 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
20cd0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
20ce0 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
20cf0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
20d00 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
20d10 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
20d20 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
20d30 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
20d40 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
20d50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20d60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
20d70 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
20d80 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
20d90 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
20da0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
20db0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
20dc0 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
20dd0 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
20de0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
20df0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
20e00 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
20e10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
20e20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
20e30 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  loc()]..*/.SQLIT
20e40 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
20e50 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
20e60 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
20e70 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
20e80 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53  c(void*, int);.S
20e90 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
20ea0 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
20eb0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
20ec0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
20ed0 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
20ee0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
20ef0 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
20f00 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
20f10 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
20f20 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
20f30 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
20f40 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
20f50 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
20f60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
20f70 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
20f80 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
20f90 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
20fa0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
20fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
20fc0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
20fd0 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
20fe0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
20ff0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
21000 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
21010 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
21020 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
21030 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
21040 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
21050 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
21060 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
21070 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
21080 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
21090 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
210a0 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
210b0 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
210c0 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
210d0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
210e0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
210f0 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
21100 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
21110 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
21120 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
21130 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
21140 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
21150 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
21160 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
21170 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
21180 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
21190 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
211a0 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
211b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
211c0 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
211d0 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
211e0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
211f0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
21200 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
21210 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
21220 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
21230 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
21240 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
21250 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
21260 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
21270 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
21280 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
21290 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
212a0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
212b0 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
212c0 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
212d0 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
212e0 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
212f0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
21300 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
21310 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
21320 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  d);.SQLITE_API s
21330 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
21340 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
21350 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
21360 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
21370 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
21380 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
21390 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
213a0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
213b0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
213c0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
213d0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
213e0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
213f0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
21400 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
21410 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
21420 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
21430 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
21440 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
21450 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
21460 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
21470 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
21480 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
21490 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
214a0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
214b0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
214c0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
214d0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
214e0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
214f0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
21500 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
21510 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
21520 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
21530 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
21540 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
21550 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fer P..**.** ^Th
21560 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
21570 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
21580 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
21590 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
215a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
215b0 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
215c0 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
215d0 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
215e0 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
215f0 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
21600 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
21610 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
21620 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75  t..** ^On all su
21630 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
21640 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
21650 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
21660 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
21670 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
21680 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
21690 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
216a0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
216b0 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54  method..*/.SQLIT
216c0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
216d0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
216e0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
216f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21700 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
21710 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
21720 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
21730 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
21740 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
21750 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
21760 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
21770 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21780 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
21790 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
217a0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
217b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
217c0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
217d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
217e0 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
217f0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
21800 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
21810 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
21820 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21830 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
21840 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
21850 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21860 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
21870 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
21880 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
21890 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
218a0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
218b0 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
218c0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
218d0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
218e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
218f0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
21900 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
21910 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
21920 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
21930 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21940 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
21950 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
21960 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
21970 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
21980 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
21990 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
219a0 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
219b0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
219c0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
219d0 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
219e0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
219f0 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
21a00 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
21a10 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
21a20 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
21a30 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
21a40 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21a50 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
21a60 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
21a70 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
21a80 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
21a90 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
21aa0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
21ab0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21ac0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
21ad0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
21ae0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
21af0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
21b00 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
21b10 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
21b20 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
21b30 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
21b40 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
21b50 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
21b60 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
21b70 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
21b80 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
21b90 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
21ba0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
21bb0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
21bc0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
21bd0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
21be0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
21bf0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
21c00 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
21c10 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
21c20 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
21c30 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
21c40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
21c50 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
21c60 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
21c70 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
21c80 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
21c90 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
21ca0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
21cb0 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
21cc0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
21cd0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
21ce0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
21cf0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
21d00 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
21d10 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
21d20 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
21d30 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
21d40 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
21d50 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
21d60 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
21d70 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
21d80 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
21d90 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
21da0 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
21db0 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
21dc0 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
21dd0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
21de0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
21df0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
21e00 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
21e10 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
21e20 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
21e30 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
21e40 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
21e50 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
21e60 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
21e70 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
21e80 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
21e90 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
21ea0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
21eb0 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
21ec0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
21ed0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
21ee0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
21ef0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
21f00 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
21f10 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
21f20 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
21f30 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
21f40 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
21f50 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
21f60 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
21f70 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
21f80 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
21f90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
21fa0 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
21fb0 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
21fc0 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
21fd0 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
21fe0 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
21ff0 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
22000 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
22010 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
22020 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
22030 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
22040 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
22050 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
22060 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
22070 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
22080 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
22090 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
220a0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
220b0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
220c0 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
220d0 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
220e0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
220f0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
22100 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
22110 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
22120 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
22130 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
22140 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
22150 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
22160 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
22170 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
22180 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
22190 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
221a0 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
221b0 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
221c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
221d0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
221e0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
221f0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
22200 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
22210 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
22220 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
22230 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
22240 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
22250 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
22260 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
22270 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
22280 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
22290 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
222a0 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
222b0 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
222c0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
222d0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
222e0 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
222f0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
22300 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
22310 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
22320 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
22330 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
22340 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
22350 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
22360 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
22370 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
22380 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
22390 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
223a0 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
223b0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
223c0 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
223d0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
223e0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
223f0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
22400 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
22410 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
22420 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
22430 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
22440 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
22450 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
22460 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
22470 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
22480 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
22490 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
224a0 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
224b0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
224c0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
224d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
224e0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
224f0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
22500 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
22510 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
22520 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
22530 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22540 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
22550 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22560 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
22570 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
22580 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
22590 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
225a0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
225b0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
225c0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
225d0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
225e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
225f0 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
22600 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
22610 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
22620 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
22630 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
22640 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
22650 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
22660 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
22670 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
22680 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
22690 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
226a0 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
226b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
226c0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
226d0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
226e0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
226f0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
22700 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
22710 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
22720 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
22730 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22740 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
22750 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
22760 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
22770 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
22780 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
22790 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
227a0 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
227b0 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
227c0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
227d0 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
227e0 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
227f0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
22800 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
22810 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
22820 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
22830 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54  change..*/.SQLIT
22840 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
22850 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
22860 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
22870 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
22880 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
22890 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
228a0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
228b0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
228c0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
228d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
228e0 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
228f0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
22900 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
22910 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
22920 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
22930 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
22940 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
22950 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
22960 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
22970 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
22980 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
22990 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
229a0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
229b0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
229c0 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
229d0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
229e0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
229f0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
22a00 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
22a10 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
22a20 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
22a30 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
22a40 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51  so used as a [SQ
22a50 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
22a60 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20  return code].** 
22a70 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
22a80 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
22a90 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
22aa0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
22ab0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
22ac0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
22ad0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
22ae0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
22af0 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
22b00 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
22b10 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
22b20 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
22b30 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
22b40 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
22b50 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
22b60 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
22b70 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
22b80 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
22b90 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
22ba0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
22bb0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
22bc0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
22bd0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
22be0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
22bf0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
22c00 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
22c10 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
22c20 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
22c30 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
22c40 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
22c50 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
22c60 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
22c70 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
22c80 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
22c90 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22ca0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
22cb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
22cc0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
22cd0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
22ce0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
22cf0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
22d00 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
22d10 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
22d20 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
22d30 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
22d40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
22d50 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
22d60 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
22d70 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
22d80 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
22d90 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
22da0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
22db0 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
22dc0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
22dd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22de0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
22df0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
22e00 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
22e10 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
22e20 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
22e30 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
22e40 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
22e50 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
22e60 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
22e70 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
22e80 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
22e90 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
22ea0 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
22eb0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
22ec0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
22ed0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
22ee0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
22ef0 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
22f00 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
22f10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22f20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
22f30 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
22f40 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
22f50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22f60 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
22f70 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
22f80 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
22f90 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22fa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22fb0 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
22fc0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
22fd0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22fe0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22ff0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
23000 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
23010 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
23020 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
23030 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
23040 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
23050 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
23060 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
23070 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
23080 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23090 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
230a0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
230b0 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
230c0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
230d0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
230e0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
230f0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
23100 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
23110 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23120 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23130 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
23140 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
23150 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
23160 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
23170 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23180 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
23190 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
231a0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
231b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
231c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
231d0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
231e0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
231f0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23200 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23210 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23220 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
23230 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
23240 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
23250 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
23260 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23270 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
23280 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
23290 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
232a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
232b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
232c0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
232d0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
232e0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
232f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23300 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23310 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
23320 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
23330 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
23340 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23350 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23360 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
23370 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
23380 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
23390 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
233a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
233b0 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
233c0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
233d0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
233e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
233f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23400 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
23410 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
23420 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
23430 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
23440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
23450 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
23460 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
23470 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
23480 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23490 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
234a0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
234b0 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
234c0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
234d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
234e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
234f0 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
23500 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
23510 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
23520 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
23530 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
23540 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23550 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
23560 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
23570 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
23580 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
23590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
235a0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
235b0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
235c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
235d0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
235e0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
235f0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
23600 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23610 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23620 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
23630 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
23640 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
23650 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
23660 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23670 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
23680 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
23690 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
236a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
236b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
236c0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
236d0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
236e0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
236f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23700 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23710 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
23720 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
23730 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
23740 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
23750 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23760 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
23770 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
23780 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
23790 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
237a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
237b0 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
237c0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
237d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
237e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
237f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23800 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
23810 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
23820 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
23830 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
23840 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23850 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
23860 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
23870 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
23880 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
23890 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
238a0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
238b0 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
238c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
238d0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
238e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
238f0 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
23900 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
23910 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
23920 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
23930 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
23940 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
23950 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
23960 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
23970 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
23980 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
23990 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
239a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
239b0 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
239c0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
239d0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
239e0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
239f0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
23a00 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
23a10 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
23a20 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
23a30 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
23a40 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
23a50 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
23a60 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
23a70 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
23a80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
23a90 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
23aa0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
23ab0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23ac0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
23ad0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
23ae0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
23af0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
23b00 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
23b10 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
23b20 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
23b30 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
23b40 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
23b50 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
23b60 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
23b70 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
23b80 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
23b90 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
23ba0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
23bb0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
23bc0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
23bd0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
23be0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
23bf0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
23c00 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
23c10 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
23c20 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
23c30 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
23c40 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
23c50 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
23c60 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
23c70 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
23c80 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
23c90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
23ca0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
23cb0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
23cc0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
23cd0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
23ce0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
23cf0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
23d00 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
23d10 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
23d20 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
23d30 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
23d40 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
23d50 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
23d60 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
23d70 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
23d80 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
23d90 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
23da0 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
23db0 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
23dc0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
23dd0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
23de0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
23df0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
23e00 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
23e10 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
23e20 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
23e30 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
23e40 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
23e50 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
23e60 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
23e70 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
23e80 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
23e90 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
23ea0 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
23eb0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
23ec0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
23ed0 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
23ee0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
23ef0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
23f00 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
23f10 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
23f20 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
23f30 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
23f40 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
23f50 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
23f60 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
23f70 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
23f80 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
23f90 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
23fa0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
23fb0 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
23fc0 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
23fd0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
23fe0 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
23ff0 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
24000 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
24010 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
24020 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
24030 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
24040 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
24050 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
24060 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
24070 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
24080 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
24090 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
240a0 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
240b0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
240c0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
240d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
240e0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
240f0 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
24100 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24110 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
24120 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
24130 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
24140 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
24150 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
24160 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
24170 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
24180 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
24190 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
241a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
241b0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
241c0 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
241d0 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
241e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
241f0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
24200 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
24210 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
24220 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
24230 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
24240 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
24250 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  ack X..**.** ^On
24260 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
24270 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
24280 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
24290 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
242a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
242b0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
242c0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
242d0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
242e0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
242f0 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
24300 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
24310 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
24320 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
24330 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
24340 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
24350 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
24360 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
24370 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
24380 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
24390 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
243a0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
243b0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
243c0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
243d0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
243e0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
243f0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
24400 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
24410 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
24420 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
24430 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
24440 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
24450 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
24460 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
24470 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
24480 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
24490 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
244a0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
244b0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
244c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
244d0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
244e0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
244f0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
24500 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24510 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
24520 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
24530 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
24540 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f  h..**.*/.SQLITE_
24550 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
24560 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
24570 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
24580 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
24590 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
245a0 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
245b0 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
245c0 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
245d0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
245e0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
245f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
24600 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
24610 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
24620 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
24630 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
24640 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
24650 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
24660 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
24670 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
24680 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
24690 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
246a0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
246b0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
246c0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
246d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
246e0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
246f0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
24700 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
24710 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
24720 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
24730 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
24740 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
24750 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
24760 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
24770 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
24780 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
24790 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
247a0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
247b0 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
247c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
247d0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
247e0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
247f0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
24800 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
24810 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
24820 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
24830 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
24840 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
24850 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
24860 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
24870 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
24880 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
24890 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
248a0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
248b0 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
248c0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
248d0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
248e0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
248f0 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
24900 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
24910 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
24920 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
24930 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
24940 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
24950 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
24960 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
24970 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
24980 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
24990 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
249a0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
249b0 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
249c0 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
249d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
249e0 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
249f0 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
24a00 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
24a10 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
24a20 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
24a30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24a40 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
24a50 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
24a60 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
24a70 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
24a80 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
24a90 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
24aa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24ab0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
24ac0 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
24ad0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
24ae0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
24af0 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
24b00 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
24b10 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
24b20 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
24b30 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
24b40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24b50 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
24b60 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
24b70 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24b80 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
24b90 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
24ba0 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
24bb0 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
24bc0 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
24bd0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
24be0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
24bf0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
24c00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
24c10 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
24c20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
24c30 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
24c40 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
24c50 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
24c60 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
24c70 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
24c80 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
24c90 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
24ca0 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
24cb0 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
24cc0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
24cd0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
24ce0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
24cf0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
24d00 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
24d10 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
24d20 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
24d30 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
24d40 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
24d50 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
24d60 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
24d70 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
24d80 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
24d90 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
24da0 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
24db0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
24dc0 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
24dd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
24de0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
24df0 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
24e00 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
24e10 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
24e20 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
24e30 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
24e40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
24e50 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
24e60 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
24e70 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
24e80 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
24e90 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
24ea0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
24eb0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
24ec0 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
24ed0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
24ee0 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
24ef0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
24f00 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
24f10 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
24f20 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
24f30 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
24f40 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
24f50 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
24f60 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
24f70 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
24f80 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
24f90 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
24fa0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
24fb0 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
24fc0 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
24fd0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
24fe0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
24ff0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
25000 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
25010 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
25020 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
25030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25040 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
25050 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
25060 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
25070 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
25080 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
25090 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
250a0 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
250b0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
250c0 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
250d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
250e0 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
250f0 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
25100 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25110 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
25120 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
25130 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
25140 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
25150 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
25160 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
25170 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
25180 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
25190 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
251a0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
251b0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
251c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
251d0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
251e0 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
251f0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
25200 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
25210 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
25220 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
25230 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
25240 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
25250 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
25260 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
25270 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
25280 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
25290 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
252a0 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
252b0 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
252c0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
252d0 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
252e0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
252f0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
25300 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
25310 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
25320 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
25330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
25340 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
25350 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
25360 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
25370 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
25380 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
25390 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
253a0 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
253b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
253c0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
253d0 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
253e0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
253f0 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
25400 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
25410 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
25420 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
25430 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
25440 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
25450 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
25460 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
25470 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
25480 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
25490 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
254a0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
254b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
254c0 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
254d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
254e0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
254f0 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
25500 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
25510 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
25520 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
25530 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
25540 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
25550 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
25560 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
25570 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
25580 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
25590 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
255a0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
255b0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
255c0 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
255d0 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
255e0 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
255f0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
25600 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
25610 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
25620 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
25630 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
25640 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
25650 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
25660 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
25670 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
25680 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
25690 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
256a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
256b0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
256c0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
256d0 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
256e0 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
256f0 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
25700 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
25710 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
25720 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
25730 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
25740 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
25750 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
25760 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
25770 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
25780 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
25790 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
257a0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
257b0 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
257c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
257d0 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
257e0 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  in the fourth ar
257f0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
25800 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
25810 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
25820 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
25830 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
25840 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
25850 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
25860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
25870 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
25880 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
25890 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
258a0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
258b0 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   As of SQLite ve
258c0 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49  rsion 3.7.7, URI
258d0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
258e0 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
258f0 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
25900 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
25910 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
25920 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
25930 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
25940 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
25950 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
25960 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
25970 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
25980 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
25990 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
259a0 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
259b0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
259c0 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
259d0 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
259e0 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
259f0 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
25a00 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
25a10 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
25a20 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
25a30 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
25a40 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
25a50 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
25a60 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
25a70 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
25a80 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
25a90 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
25aa0 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
25ab0 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
25ac0 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
25ad0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
25ae0 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
25af0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
25b00 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
25b10 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
25b20 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
25b30 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
25b40 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
25b50 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
25b60 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
25b70 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
25b80 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
25b90 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
25ba0 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
25bb0 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
25bc0 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
25bd0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
25be0 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
25bf0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
25c00 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
25c10 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
25c20 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
25c30 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77   path. .** ^On w
25c40 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73  indows, the firs
25c50 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
25c60 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20  n absolute path 
25c70 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73  .** is a drive s
25c80 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e  pecification (e.
25c90 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20  g. "C:")..**.** 
25ca0 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
25cb0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
25cc0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
25cd0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
25ce0 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
25cf0 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
25d00 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
25d10 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
25d20 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
25d30 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
25d40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
25d50 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
25d60 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77  prets the follow
25d70 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20  ing three query 
25d80 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
25d90 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
25da0 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
25db0 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
25dc0 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
25dd0 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
25de0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
25df0 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
25e00 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
25e10 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
25e20 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
25e30 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
25e40 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
25e50 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
25e60 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
25e70 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
25e80 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
25e90 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
25ea0 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
25eb0 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
25ec0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
25ed0 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
25ee0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
25ef0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
25f00 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
25f10 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
25f20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
25f30 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
25f40 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
25f50 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
25f60 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
25f70 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
25f80 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
25f90 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
25fa0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
25fb0 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
25fc0 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
25fd0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
25fe0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
25ff0 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
26000 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
26010 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
26020 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
26030 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
26040 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
26050 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
26060 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
26070 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
26080 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
26090 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
260a0 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
260b0 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
260c0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
260d0 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
260e0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
260f0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
26100 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
26110 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
26120 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
26130 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
26140 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
26150 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
26160 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
26170 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
26180 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
26190 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
261a0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
261b0 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
261c0 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
261d0 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
261e0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
261f0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
26200 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
26210 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
26220 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
26230 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
26240 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
26250 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
26260 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
26270 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
26280 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
26290 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
262a0 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
262b0 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
262c0 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
262d0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
262e0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
262f0 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
26300 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
26310 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
26320 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
26330 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
26340 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
26350 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
26360 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
26370 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
26380 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
26390 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
263a0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
263b0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
263c0 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
263d0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
263e0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
263f0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
26400 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
26410 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
26420 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
26430 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
26440 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
26450 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
26460 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
26470 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
26480 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
26490 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
264a0 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
264b0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
264c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
264d0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
264e0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
264f0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
26500 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
26510 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
26520 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
26530 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
26540 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
26550 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
26560 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
26570 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
26580 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
26590 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
265a0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
265b0 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c  HE flag..** </ul
265c0 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
265d0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
265e0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
265f0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
26600 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
26610 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
26620 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
26630 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
26640 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
26650 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
26660 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
26670 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
26680 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
26690 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
266a0 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
266b0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
266c0 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
266d0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
266e0 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
266f0 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
26700 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
26710 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
26720 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
26730 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
26740 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
26750 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
26760 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
26770 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
26780 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
26790 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
267a0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
267b0 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
267c0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
267d0 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
267e0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
267f0 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
26800 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
26810 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
26820 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
26830 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
26840 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
26850 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
26860 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
26870 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
26880 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
26890 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
268a0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
268b0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
268c0 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
268d0 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
268e0 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
268f0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
26900 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
26910 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
26920 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
26930 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
26940 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
26950 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
26960 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
26970 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
26980 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
26990 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
269a0 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
269b0 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
269c0 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
269d0 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
269e0 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
269f0 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
26a00 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
26a10 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
26a20 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
26a30 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
26a40 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
26a50 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
26a60 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
26a70 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
26a80 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
26a90 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
26aa0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
26ab0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
26ac0 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
26ad0 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
26ae0 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
26af0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
26b00 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
26b10 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
26b20 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
26b30 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
26b40 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
26b50 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
26b60 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26b70 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f  db?vfs=unix-nolo
26b80 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  ck <td>.**      
26b90 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
26ba0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26bb0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
26bc0 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f  ial VFS "unix-no
26bd0 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  lock"..** <tr><t
26be0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
26bf0 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
26c00 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26c10 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
26c20 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
26c30 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
26c40 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
26c50 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
26c60 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
26c70 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
26c80 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
26c90 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
26ca0 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
26cb0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
26cc0 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
26cd0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
26ce0 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
26cf0 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
26d00 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
26d10 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
26d20 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
26d30 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
26d40 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
26d50 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
26d60 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
26d70 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
26d80 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
26d90 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
26da0 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
26db0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
26dc0 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
26dd0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
26de0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
26df0 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
26e00 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
26e10 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
26e20 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
26e30 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
26e40 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
26e50 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
26e60 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
26e70 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
26e80 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
26e90 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
26ea0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
26eb0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
26ec0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
26ed0 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
26ee0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
26ef0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
26f00 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
26f10 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
26f20 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
26f30 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
26f40 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
26f50 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
26f60 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
26f70 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
26f80 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
26f90 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
26fa0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
26fb0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
26fc0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
26fd0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
26fe0 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
26ff0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
27000 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
27010 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
27020 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
27030 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
27040 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
27050 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
27060 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
27070 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
27080 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
27090 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
270a0 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
270b0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
270c0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
270d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
270e0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
270f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
27100 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
27110 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
27120 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
27130 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
27140 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
27150 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
27160 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
27170 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
27180 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
27190 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
271a0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
271b0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
271c0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
271d0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
271e0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
271f0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
27200 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
27210 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
27220 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
27230 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
27240 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
27250 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
27260 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
27270 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
27280 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
27290 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
272a0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
272b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
272c0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
272d0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
272e0 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
272f0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
27300 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
27310 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
27320 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
27330 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
27340 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
27350 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
27360 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
27370 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
27380 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
27390 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
273a0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
273b0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
273c0 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
273d0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
273e0 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
273f0 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
27400 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27410 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
27420 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
27430 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
27440 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
27450 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
27460 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
27470 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
27480 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
27490 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
274a0 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
274b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
274c0 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
274d0 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
274e0 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
274f0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
27500 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
27510 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
27520 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
27530 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
27540 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
27550 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
27560 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
27570 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
27580 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
27590 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
275a0 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
275b0 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
275c0 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
275d0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
275e0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
275f0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
27600 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
27610 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
27620 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
27630 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27640 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
27650 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
27660 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
27670 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
27680 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
27690 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
276a0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
276b0 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
276c0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
276d0 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
276e0 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
276f0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
27700 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
27710 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
27720 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
27730 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
27740 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
27750 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
27760 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
27770 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
27780 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
27790 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
277a0 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
277b0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
277c0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
277d0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
277e0 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
277f0 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
27800 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
27810 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
27820 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
27830 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
27840 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
27850 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
27860 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
27870 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
27880 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
27890 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
278a0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
278b0 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
278c0 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
278d0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
278e0 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
278f0 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
27900 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
27910 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
27920 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
27930 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
27940 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
27950 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
27960 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
27970 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
27980 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
27990 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
279a0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
279b0 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
279c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
279d0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
279e0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
279f0 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
27a00 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
27a10 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
27a20 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
27a30 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
27a40 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
27a50 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
27a60 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
27a70 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
27a80 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
27a90 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
27aa0 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
27ab0 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
27ac0 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
27ad0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
27ae0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
27af0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
27b00 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
27b10 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
27b20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
27b30 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
27b40 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49  r *zParam);.SQLI
27b50 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27b60 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
27b70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
27b80 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
27b90 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
27ba0 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  lt);.SQLITE_API 
27bb0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
27bc0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
27bd0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
27be0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
27bf0 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
27c00 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
27c10 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
27c20 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
27c30 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
27c40 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27c50 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
27c60 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
27c70 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
27c80 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
27c90 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
27ca0 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
27cb0 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
27cc0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
27cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27ce0 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
27cf0 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
27d00 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
27d10 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
27d20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
27d30 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
27d40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
27d50 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
27d60 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
27d70 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
27d80 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
27d90 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
27da0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
27db0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
27dc0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
27dd0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
27de0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
27df0 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
27e00 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
27e10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
27e20 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
27e30 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
27e40 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
27e50 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
27e60 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
27e70 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
27e80 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
27e90 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
27ea0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
27eb0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
27ec0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
27ed0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
27ee0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
27ef0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
27f00 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
27f10 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
27f20 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
27f30 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
27f40 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
27f50 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
27f60 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
27f70 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
27f80 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
27f90 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
27fa0 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
27fb0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
27fc0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
27fd0 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
27fe0 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
27ff0 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
28000 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
28010 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
28020 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
28030 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
28040 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
28050 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
28060 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
28070 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
28080 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
28090 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
280a0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
280b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
280c0 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
280d0 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
280e0 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
280f0 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
28100 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
28110 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
28120 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
28130 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
28140 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
28150 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
28160 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
28170 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
28180 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
28190 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
281a0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
281b0 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
281c0 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
281d0 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
281e0 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
281f0 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
28200 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
28210 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
28220 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
28230 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
28240 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
28250 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
28260 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
28270 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
28280 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
28290 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
282a0 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
282b0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
282c0 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
282d0 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
282e0 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
282f0 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
28300 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
28310 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
28320 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
28330 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
28340 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
28350 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
28360 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
28370 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
28380 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
28390 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
283a0 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
283b0 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49   be set..*/.SQLI
283c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
283d0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
283e0 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
283f0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
28400 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
28410 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53  (sqlite3 *db);.S
28420 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
28430 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
28440 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
28450 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
28460 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
28470 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
28480 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
28490 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
284a0 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
284b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
284c0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
284d0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
284e0 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
284f0 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
28500 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
28510 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
28520 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
28530 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
28540 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
28550 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
28560 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
28570 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
28580 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
28590 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53  a.** "compiled S
285a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
285b0 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
285c0 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20  atement"..**.** 
285d0 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
285e0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
285f0 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
28600 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
28610 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
28620 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
28630 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
28640 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
28650 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
28660 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
28670 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
28680 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   [host parameter
28690 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
286a0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
286b0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
286c0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
286d0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
286e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
286f0 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
28700 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
28710 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
28720 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
28730 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
28740 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
28750 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
28760 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
28770 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
28780 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
28790 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
287a0 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
287b0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
287c0 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
287d0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
287e0 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
287f0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
28800 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
28810 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
28820 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
28830 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
28840 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
28850 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a  time Limits.**.*
28860 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
28870 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
28880 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
28890 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
288a0 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
288b0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
288c0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
288d0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
288e0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
288f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28900 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
28910 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
28920 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
28930 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
28940 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
28950 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
28960 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
28970 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
28980 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
28990 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
289a0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
289b0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
289c0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
289d0 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
289e0 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
289f0 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
28a00 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
28a10 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
28a20 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
28a30 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
28a40 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
28a50 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
28a60 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
28a70 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
28a80 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
28a90 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
28aa0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
28ab0 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
28ac0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
28ad0 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
28ae0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
28af0 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
28b00 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
28b10 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
28b20 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
28b30 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
28b40 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
28b50 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
28b60 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
28b70 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
28b80 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
28b90 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
28ba0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
28bb0 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
28bc0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
28bd0 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
28be0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
28bf0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
28c00 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
28c10 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
28c20 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
28c30 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
28c40 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
28c50 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
28c60 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
28c70 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
28c80 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
28c90 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
28ca0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
28cb0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
28cc0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
28cd0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
28ce0 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
28cf0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
28d00 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
28d10 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
28d20 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
28d30 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
28d40 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
28d50 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
28d60 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
28d70 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
28d80 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
28d90 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
28da0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
28db0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
28dc0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
28dd0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
28de0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
28df0 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
28e00 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
28e10 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
28e20 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
28e30 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
28e40 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
28e50 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
28e60 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
28e70 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
28e80 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
28e90 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
28ea0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
28eb0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
28ec0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
28ed0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
28ee0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
28ef0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
28f00 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
28f10 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
28f20 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
28f30 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
28f40 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
28f50 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
28f60 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
28f70 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
28f80 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
28f90 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
28fa0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
28fb0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
28fc0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
28fd0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
28fe0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
28ff0 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ases..*/.SQLITE_
29000 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29010 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
29020 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
29030 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
29040 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
29050 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
29060 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
29070 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
29080 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
29090 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
290a0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
290b0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
290c0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
290d0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
290e0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
290f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
29100 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
29110 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
29120 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
29130 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
29140 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
29150 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
29160 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
29170 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
29180 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
29190 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
291a0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
291b0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
291c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
291d0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
291e0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
291f0 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
29200 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
29210 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
29220 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29230 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
29240 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
29250 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
29260 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
29270 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
29280 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
29290 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
292a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
292b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
292c0 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
292d0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
292e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
292f0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29300 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
29310 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
29320 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
29330 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
29340 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
29350 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
29360 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
29370 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
29380 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
29390 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
293a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
293b0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
293c0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
293d0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
293e0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
293f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
29400 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
29410 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
29420 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
29430 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29440 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
29450 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
29460 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
29470 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
29480 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29490 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
294a0 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
294b0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
294c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
294d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
294e0 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
294f0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
29500 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29510 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29520 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
29530 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
29540 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
29550 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
29560 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
29570 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
29580 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
29590 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
295a0 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
295b0 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
295c0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
295d0 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
295e0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
295f0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
29600 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
29610 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
29620 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
29630 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29640 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
29650 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
29660 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
29670 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29680 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
29690 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
296a0 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
296b0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
296c0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
296d0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
296e0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
296f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29700 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
29710 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
29720 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29730 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
29740 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
29750 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
29760 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
29770 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
29780 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
29790 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
297a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
297b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
297c0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
297d0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
297e0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
297f0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
29800 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
29810 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
29820 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
29830 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
29840 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
29850 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
29860 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
29870 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
29880 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
29890 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
298a0 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
298b0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
298c0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
298d0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
298e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
298f0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
29900 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
29910 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
29920 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
29930 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
29940 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
29950 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
29960 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
29970 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
29980 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
29990 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
299a0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
299b0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
299c0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
299d0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
299e0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
299f0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
29a00 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29a10 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
29a20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
29a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29a40 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
29a50 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
29a60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29a70 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
29a80 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
29a90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29aa0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
29ab0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
29ac0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29ad0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
29ae0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
29af0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29b00 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
29b10 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
29b20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
29b30 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
29b40 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
29b50 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
29b60 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
29b70 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
29b80 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
29b90 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
29ba0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
29bb0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
29bc0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
29bd0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
29be0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29bf0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
29c00 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
29c10 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
29c20 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
29c30 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
29c40 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
29c50 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
29c60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
29c70 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
29c80 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
29c90 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
29ca0 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
29cb0 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
29cc0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
29cd0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
29ce0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
29cf0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
29d00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
29d10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
29d20 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
29d30 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
29d40 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
29d50 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
29d60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29d70 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
29d80 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
29d90 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
29da0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
29db0 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
29dc0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
29dd0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
29de0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
29df0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
29e00 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
29e10 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
29e20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
29e30 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
29e40 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
29e50 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
29e60 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
29e70 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
29e80 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
29e90 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
29ea0 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
29eb0 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
29ec0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
29ed0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
29ee0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
29ef0 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
29f00 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
29f10 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
29f20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
29f30 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
29f40 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
29f50 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
29f60 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
29f70 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
29f80 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
29f90 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
29fa0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
29fb0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
29fc0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
29fd0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
29fe0 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
29ff0 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
2a000 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
2a010 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
2a020 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
2a030 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
2a040 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
2a050 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
2a060 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
2a070 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
2a080 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
2a090 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
2a0a0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
2a0b0 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
2a0c0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
2a0d0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
2a0e0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
2a0f0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
2a100 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
2a110 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
2a120 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
2a130 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2a140 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
2a150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a160 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
2a170 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
2a180 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a190 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
2a1a0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
2a1b0 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
2a1c0 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
2a1d0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
2a1e0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
2a1f0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
2a200 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
2a210 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
2a220 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
2a230 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
2a240 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
2a250 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
2a260 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
2a270 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
2a280 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2a290 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2a2a0 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
2a2b0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2a2c0 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
2a2d0 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
2a2e0 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
2a2f0 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
2a300 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
2a310 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
2a320 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
2a330 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
2a340 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2a350 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2a360 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2a370 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
2a380 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a390 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
2a3a0 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
2a3b0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
2a3c0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
2a3d0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
2a3e0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
2a3f0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
2a400 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
2a410 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
2a420 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
2a430 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
2a440 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
2a450 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2a460 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
2a470 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2a480 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
2a490 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
2a4a0 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
2a4b0 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
2a4c0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
2a4d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
2a4e0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
2a4f0 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
2a500 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
2a510 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
2a520 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
2a530 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
2a540 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
2a550 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2a560 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
2a570 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
2a580 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
2a590 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
2a5a0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
2a5b0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
2a5c0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
2a5d0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
2a5e0 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
2a5f0 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
2a600 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
2a610 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
2a620 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
2a630 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
2a640 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
2a650 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
2a660 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
2a670 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
2a680 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a690 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
2a6a0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
2a6b0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
2a6c0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
2a6d0 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
2a6e0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
2a6f0 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
2a700 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a710 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
2a720 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
2a730 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
2a740 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
2a750 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
2a760 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
2a770 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
2a780 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2a790 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
2a7a0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
2a7b0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
2a7c0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
2a7d0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
2a7e0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
2a7f0 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
2a800 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
2a810 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
2a820 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
2a830 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2a840 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
2a850 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
2a860 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
2a870 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
2a880 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
2a890 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
2a8a0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
2a8b0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2a8c0 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
2a8d0 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
2a8e0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
2a8f0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
2a900 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
2a910 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
2a920 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
2a930 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
2a940 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
2a950 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
2a960 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
2a970 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
2a980 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
2a990 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
2a9a0 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
2a9b0 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
2a9c0 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
2a9d0 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
2a9e0 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
2a9f0 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
2aa00 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2aa10 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2aa20 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
2aa30 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
2aa40 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
2aa50 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
2aa60 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2aa70 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
2aa80 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
2aa90 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
2aaa0 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
2aab0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2aac0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
2aad0 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
2aae0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ol>.*/.SQLI
2aaf0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2ab00 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
2ab10 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2ab20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2ab30 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2ab40 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2ab50 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2ab60 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2ab70 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2ab80 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2ab90 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2aba0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2abb0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2abc0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2abd0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2abe0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2abf0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2ac00 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2ac10 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2ac20 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2ac30 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
2ac40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2ac50 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
2ac60 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2ac70 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2ac80 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2ac90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2aca0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2acb0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2acc0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2acd0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2ace0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2acf0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2ad00 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2ad10 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2ad20 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2ad30 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2ad40 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2ad50 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2ad60 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2ad70 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2ad80 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
2ad90 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ada0 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
2adb0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2adc0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2add0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2ade0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2adf0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2ae00 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2ae10 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2ae20 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2ae30 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2ae40 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2ae50 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2ae60 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2ae70 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2ae80 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2ae90 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2aea0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2aeb0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2aec0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2aed0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
2aee0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2aef0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2af00 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2af10 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2af20 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2af30 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2af40 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2af50 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2af60 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
2af70 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2af80 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2af90 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2afa0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2afb0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2afc0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2afd0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2afe0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2aff0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2b000 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2b010 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2b020 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2b030 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b040 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
2b050 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
2b060 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
2b070 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
2b080 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
2b090 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
2b0a0 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
2b0b0 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
2b0c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2b0d0 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
2b0e0 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
2b0f0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
2b100 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2b110 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2b120 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b130 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  16_v2()]..*/.SQL
2b140 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2b150 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
2b160 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2b170 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2b180 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2b190 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
2b1a0 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
2b1b0 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
2b1c0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2b1d0 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
2b1e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2b1f0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
2b200 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
2b210 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2b220 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
2b230 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
2b240 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
2b250 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
2b260 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
2b270 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
2b280 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b290 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
2b2a0 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
2b2b0 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
2b2c0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2b2d0 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
2b2e0 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
2b2f0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2b300 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
2b310 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
2b320 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
2b330 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
2b340 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
2b350 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
2b360 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
2b370 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
2b380 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2b390 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
2b3a0 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
2b3b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
2b3c0 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
2b3d0 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
2b3e0 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
2b3f0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
2b400 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
2b410 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
2b420 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
2b430 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
2b440 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2b450 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
2b460 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2b470 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
2b480 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
2b490 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
2b4a0 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
2b4b0 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
2b4c0 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
2b4d0 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
2b4e0 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
2b4f0 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
2b500 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2b510 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2b520 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
2b530 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
2b540 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
2b550 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
2b560 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2b570 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
2b580 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
2b590 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
2b5a0 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
2b5b0 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
2b5c0 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
2b5d0 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
2b5e0 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
2b5f0 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
2b600 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2b610 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
2b620 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
2b630 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
2b640 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
2b650 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
2b660 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
2b670 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
2b680 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
2b690 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
2b6a0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2b6b0 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
2b6c0 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  sk..*/.SQLITE_AP
2b6d0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
2b6e0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
2b6f0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2b700 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b710 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2b720 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2b730 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
2b740 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
2b750 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2b760 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
2b770 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2b780 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
2b790 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b7a0 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
2b7b0 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
2b7c0 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
2b7d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2b7e0 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75  ] but has not ru
2b7f0 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
2b800 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a  and/or has not .
2b810 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
2b820 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2b830 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
2b840 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2b850 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
2b860 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
2b870 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
2b880 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
2b890 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
2b8a0 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
2b8b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2b8c0 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
2b8d0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2b8e0 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
2b8f0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2b900 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2b910 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
2b920 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2b930 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2b940 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
2b950 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2b960 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
2b970 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
2b980 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
2b990 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
2b9a0 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
2b9b0 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
2b9c0 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
2b9d0 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
2b9e0 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
2b9f0 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
2ba00 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
2ba10 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
2ba20 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
2ba30 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
2ba40 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
2ba50 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c  ion open..*/.SQL
2ba60 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2ba70 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71  te3_stmt_busy(sq
2ba80 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2ba90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2baa0 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
2bab0 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
2bac0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
2bad0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2bae0 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
2baf0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
2bb00 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
2bb10 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
2bb20 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
2bb30 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
2bb40 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
2bb50 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
2bb60 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
2bb70 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
2bb80 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
2bb90 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
2bba0 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
2bbb0 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
2bbc0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
2bbd0 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
2bbe0 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
2bbf0 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
2bc00 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
2bc10 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
2bc20 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2bc30 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
2bc40 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
2bc50 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
2bc60 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
2bc70 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
2bc80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2bc90 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
2bca0 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
2bcb0 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
2bcc0 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
2bcd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2bce0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
2bcf0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
2bd00 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
2bd10 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
2bd20 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
2bd30 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
2bd40 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
2bd50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2bd60 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
2bd70 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
2bd80 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
2bd90 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
2bda0 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
2bdb0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
2bdc0 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
2bdd0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
2bde0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2bdf0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2be00 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
2be10 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
2be20 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2be30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2be40 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
2be50 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
2be60 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
2be70 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
2be80 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
2be90 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2bea0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
2beb0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
2bec0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
2bed0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
2bee0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
2bef0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
2bf00 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
2bf10 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
2bf20 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
2bf30 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
2bf40 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
2bf50 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
2bf60 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
2bf70 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2bf80 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
2bf90 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
2bfa0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
2bfb0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
2bfc0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
2bfd0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
2bfe0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
2bff0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
2c000 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
2c010 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2c020 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2c030 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2c040 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2c050 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
2c060 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
2c070 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
2c080 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2c090 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
2c0a0 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
2c0b0 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
2c0c0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
2c0d0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
2c0e0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2c0f0 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
2c100 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
2c110 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2c120 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2c130 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2c140 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2c150 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
2c160 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
2c170 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c180 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
2c190 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
2c1a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2c1b0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2c1c0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
2c1d0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
2c1e0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
2c1f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2c200 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
2c210 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2c220 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
2c230 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c240 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
2c250 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
2c260 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
2c270 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
2c280 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
2c290 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
2c2a0 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
2c2b0 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
2c2c0 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
2c2d0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
2c2e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
2c2f0 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
2c300 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
2c310 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
2c320 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
2c330 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
2c340 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c350 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2c360 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
2c370 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2c380 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
2c390 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
2c3a0 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
2c3b0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
2c3c0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
2c3d0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
2c3e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
2c3f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2c400 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2c410 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
2c420 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
2c430 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2c440 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
2c450 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2c460 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
2c470 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
2c480 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
2c490 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2c4a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
2c4b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
2c4c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
2c4d0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
2c4e0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2c4f0 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
2c500 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
2c510 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
2c520 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
2c530 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
2c540 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
2c550 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
2c560 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
2c570 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a  ter binding}.**.
2c580 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
2c590 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
2c5a0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
2c5b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2c5c0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
2c5d0 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
2c5e0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
2c5f0 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
2c600 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
2c610 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
2c620 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
2c630 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
2c640 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
2c650 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
2c660 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
2c670 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
2c680 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
2c690 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
2c6a0 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
2c6b0 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
2c6c0 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
2c6d0 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
2c6e0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
2c6f0 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
2c700 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
2c710 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
2c720 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
2c730 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
2c740 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
2c750 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
2c760 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
2c770 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2c780 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
2c790 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
2c7a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2c7b0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2c7c0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
2c7d0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
2c7e0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
2c7f0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
2c800 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
2c810 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2c820 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
2c830 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
2c840 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
2c850 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2c860 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
2c870 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
2c880 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
2c890 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
2c8a0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2c8b0 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
2c8c0 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
2c8d0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
2c8e0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
2c8f0 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
2c900 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
2c910 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
2c920 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
2c930 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
2c940 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
2c950 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
2c960 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
2c970 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
2c980 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2c990 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2c9a0 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
2c9b0 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
2c9c0 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
2c9d0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
2c9e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
2c9f0 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
2ca00 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
2ca10 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
2ca20 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
2ca30 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
2ca40 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2ca50 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
2ca60 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
2ca70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2ca80 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
2ca90 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
2caa0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
2cab0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
2cac0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
2cad0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2cae0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2caf0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2cb00 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2cb10 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c  _blob() is a NUL
2cb20 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
2cb30 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2cb40 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65  ter.** is ignore
2cb50 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65  d and the end re
2cb60 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65  sult is the same
2cb70 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   as sqlite3_bind
2cb80 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  _null()..**.** ^
2cb90 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
2cba0 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
2cbb0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
2cbc0 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
2cbd0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
2cbe0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
2cbf0 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
2cc00 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
2cc10 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2cc20 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
2cc30 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
2cc40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2cc50 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
2cc60 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
2cc70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2cc80 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2cc90 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2cca0 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e  text16().** is n
2ccb0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
2ccc0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2ccd0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
2cce0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2ccf0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
2cd00 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2cd10 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
2cd20 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2cd30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2cd40 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c  b() is negative,
2cd50 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68   then.** the beh
2cd60 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2cd70 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d  ed..** If a non-
2cd80 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20  negative fourth 
2cd90 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f  parameter is pro
2cda0 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33  vided to sqlite3
2cdb0 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20  _bind_text().** 
2cdc0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2cdd0 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68  text16() then th
2cde0 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
2cdf0 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
2ce00 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
2ce10 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
2ce20 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
2ce30 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
2ce40 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
2ce50 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
2ce60 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
2ce70 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
2ce80 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
2ce90 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
2cea0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2ceb0 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
2cec0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
2ced0 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
2cee0 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
2cef0 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
2cf00 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
2cf10 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
2cf20 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
2cf30 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
2cf40 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2cf50 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2cf60 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2cf70 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2cf80 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
2cf90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
2cfa0 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
2cfb0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
2cfc0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2cfd0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
2cfe0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
2cff0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2d000 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
2d010 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
2d020 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
2d030 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
2d040 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
2d050 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2d060 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  _bind_blob(),.**
2d070 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d080 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  xt(), or sqlite3
2d090 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66  _bind_text16() f
2d0a0 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74  ails.  .** ^If t
2d0b0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2d0c0 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
2d0d0 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
2d0e0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
2d0f0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
2d100 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
2d110 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
2d120 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
2d130 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
2d140 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
2d150 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
2d160 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
2d170 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
2d180 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
2d190 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
2d1a0 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
2d1b0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
2d1c0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
2d1d0 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
2d1e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2d1f0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2d200 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
2d210 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2d220 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
2d230 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
2d240 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
2d250 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
2d260 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
2d270 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
2d280 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
2d290 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
2d2a0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
2d2b0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
2d2c0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
2d2d0 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
2d2e0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
2d2f0 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
2d300 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
2d310 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
2d320 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
2d330 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
2d340 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
2d350 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
2d360 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
2d370 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
2d380 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
2d390 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
2d3a0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
2d3b0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
2d3c0 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
2d3d0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2d3e0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2d3f0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
2d400 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
2d410 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d420 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
2d430 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d440 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
2d450 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2d460 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
2d470 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
2d480 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2d490 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
2d4a0 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
2d4b0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2d4c0 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
2d4d0 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
2d4e0 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
2d4f0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2d500 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
2d510 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
2d520 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
2d530 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2d540 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
2d550 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
2d560 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
2d570 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
2d580 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
2d590 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
2d5a0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
2d5b0 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
2d5c0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
2d5d0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
2d5e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2d5f0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
2d600 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
2d610 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
2d620 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
2d630 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2d640 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2d650 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2d660 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2d670 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2d680 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2d690 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2d6a0 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2d6b0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2d6c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2d6d0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2d6e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2d6f0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2d700 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
2d710 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2d720 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2d730 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2d740 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
2d750 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d760 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2d770 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
2d780 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2d790 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2d7a0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2d7b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
2d7c0 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  le);.SQLITE_API 
2d7d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2d7e0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2d7f0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53  t*, int, int);.S
2d800 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2d810 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
2d820 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d830 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
2d840 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
2d850 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2d860 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
2d870 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  mt*, int);.SQLIT
2d880 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2d890 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
2d8a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d8b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2d8c0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
2d8d0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2d8e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2d8f0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2d900 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2d910 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2d920 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2d930 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2d940 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2d950 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d960 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
2d970 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2d980 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2d990 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2d9a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d9b0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
2d9c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2d9d0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2d9e0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
2d9f0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2da00 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
2da10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
2da20 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
2da30 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
2da40 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
2da50 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2da60 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2da70 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2da80 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2da90 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2daa0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2dab0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2dac0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2dad0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2dae0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2daf0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2db00 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2db10 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2db20 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2db30 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2db40 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2db50 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2db60 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2db70 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2db80 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2db90 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2dba0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2dbb0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2dbc0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2dbd0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2dbe0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2dbf0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2dc00 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2dc10 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2dc20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2dc30 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2dc40 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2dc50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2dc60 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2dc70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2dc80 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2dc90 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2dca0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2dcb0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
2dcc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2dcd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2dce0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
2dcf0 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e  arameter.**.** ^
2dd00 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2dd10 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2dd20 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
2dd30 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
2dd40 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
2dd50 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
2dd60 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2dd70 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2dd80 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
2dd90 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2dda0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2ddb0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2ddc0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
2ddd0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
2dde0 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
2ddf0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2de00 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
2de10 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
2de20 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2de30 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
2de40 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
2de50 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
2de60 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
2de70 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
2de80 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2de90 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
2dea0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
2deb0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
2dec0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
2ded0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
2dee0 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
2def0 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
2df00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2df10 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
2df20 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2df30 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
2df40 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
2df50 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
2df60 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
2df70 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
2df80 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
2df90 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
2dfa0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2dfb0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
2dfc0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
2dfd0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
2dfe0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
2dff0 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
2e000 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
2e010 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
2e020 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2e030 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2e040 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2e050 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2e060 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2e070 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2e080 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2e090 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e0a0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2e0b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2e0c0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2e0d0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2e0e0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2e0f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e100 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
2e110 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
2e120 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e130 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
2e140 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
2e150 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65  n Name.**.** ^Re
2e160 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
2e170 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
2e180 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
2e190 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
2e1a0 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
2e1b0 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
2e1c0 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
2e1d0 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
2e1e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
2e1f0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2e200 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
2e210 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
2e220 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
2e230 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
2e240 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
2e250 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
2e260 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
2e270 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
2e280 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
2e290 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
2e2a0 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
2e2b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2e2c0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2e2d0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e2e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e2f0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2e300 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2e310 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e320 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2e330 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e340 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2e350 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2e360 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2e370 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2e380 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
2e390 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2e3a0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
2e3b0 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
2e3c0 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
2e3d0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2e3e0 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
2e3f0 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
2e400 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
2e410 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
2e420 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
2e430 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2e440 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
2e450 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
2e460 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2e470 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
2e480 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
2e490 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
2e4a0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54  o NULL..*/.SQLIT
2e4b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2e4c0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2e4d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2e4e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e4f0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
2e500 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
2e510 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  Set.**.** ^Retur
2e520 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
2e530 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2e540 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
2e550 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
2e560 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e570 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
2e580 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
2e590 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
2e5a0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
2e5b0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
2e5c0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
2e5d0 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
2e5e0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2e5f0 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
2e600 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
2e610 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2e620 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
2e630 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2e640 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e650 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
2e660 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2e670 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2e680 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2e690 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
2e6a0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
2e6b0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
2e6c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2e6d0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2e6e0 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
2e6f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2e700 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2e710 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2e720 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2e730 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
2e740 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
2e750 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2e760 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
2e770 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2e780 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
2e790 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2e7a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2e7b0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
2e7c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2e7d0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2e7e0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2e7f0 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
2e800 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2e810 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
2e820 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
2e830 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
2e840 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
2e850 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2e860 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
2e870 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
2e880 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
2e890 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
2e8a0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
2e8b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e8c0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2e8d0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2e8e0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2e8f0 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2e900 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2e910 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2e920 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2e930 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2e940 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2e950 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2e960 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
2e970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2e980 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
2e990 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
2e9a0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
2e9b0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
2e9c0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
2e9d0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
2e9e0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
2e9f0 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
2ea00 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
2ea10 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
2ea20 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
2ea30 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2ea40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2ea50 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
2ea60 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
2ea70 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
2ea80 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
2ea90 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
2eaa0 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
2eab0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
2eac0 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
2ead0 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
2eae0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
2eaf0 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
2eb00 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
2eb10 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
2eb20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
2eb30 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  xt..*/.SQLITE_AP
2eb40 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2eb50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2eb60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2eb70 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
2eb80 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2eb90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2eba0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2ebb0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
2ebc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
2ebd0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
2ebe0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2ebf0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2ec00 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
2ec10 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
2ec20 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
2ec30 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
2ec40 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
2ec50 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
2ec60 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
2ec70 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
2ec80 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
2ec90 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
2eca0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2ecb0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
2ecc0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
2ecd0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
2ece0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
2ecf0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2ed00 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
2ed10 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
2ed20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
2ed30 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
2ed40 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2ed50 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
2ed60 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
2ed70 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
2ed80 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
2ed90 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
2eda0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
2edb0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
2edc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2edd0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
2ede0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2edf0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2ee00 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2ee10 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2ee20 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2ee30 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2ee40 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2ee50 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2ee60 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2ee70 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2ee80 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
2ee90 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
2eea0 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
2eeb0 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
2eec0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
2eed0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
2eee0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
2eef0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
2ef00 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
2ef10 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
2ef20 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
2ef30 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2ef40 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
2ef50 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2ef60 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2ef70 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2ef80 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2ef90 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
2efa0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
2efb0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
2efc0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
2efd0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
2efe0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
2eff0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
2f000 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
2f010 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
2f020 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
2f030 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
2f040 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2f050 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
2f060 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
2f070 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
2f080 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
2f090 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
2f0a0 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
2f0b0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
2f0c0 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
2f0d0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
2f0e0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
2f0f0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2f100 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
2f110 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
2f120 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
2f130 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2f140 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2f150 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
2f160 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
2f170 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
2f180 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
2f190 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
2f1a0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
2f1b0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
2f1c0 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
2f1d0 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
2f1e0 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
2f1f0 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
2f200 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
2f210 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
2f220 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
2f230 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
2f240 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2f250 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2f260 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2f270 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2f280 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2f290 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2f2a0 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
2f2b0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2f2c0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2f2d0 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
2f2e0 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
2f2f0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
2f300 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
2f310 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
2f320 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2f330 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
2f340 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2f350 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2f360 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2f370 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
2f380 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2f390 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
2f3a0 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
2f3b0 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
2f3c0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
2f3d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
2f3e0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
2f3f0 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
2f400 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2f410 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2f420 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
2f430 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2f440 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2f450 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
2f460 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2f470 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2f480 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2f490 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2f4a0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2f4b0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2f4c0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2f4d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f4e0 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2f4f0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2f500 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2f510 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2f520 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
2f530 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2f540 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2f550 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2f560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2f570 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2f580 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2f590 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2f5a0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2f5b0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
2f5c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2f5d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f5e0 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
2f5f0 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
2f600 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
2f610 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2f620 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
2f630 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2f640 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
2f650 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
2f660 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
2f670 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2f680 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
2f690 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
2f6a0 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
2f6b0 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
2f6c0 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
2f6d0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2f6e0 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
2f6f0 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
2f700 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
2f710 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
2f720 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2f730 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2f740 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
2f750 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2f760 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
2f770 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2f780 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
2f790 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2f7a0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
2f7b0 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
2f7c0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
2f7d0 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
2f7e0 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
2f7f0 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
2f800 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
2f810 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
2f820 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
2f830 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
2f840 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
2f850 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
2f860 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
2f870 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
2f880 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
2f890 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
2f8a0 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
2f8b0 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
2f8c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
2f8d0 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
2f8e0 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
2f8f0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
2f900 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2f910 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
2f920 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
2f930 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
2f940 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
2f950 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
2f960 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
2f970 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
2f980 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
2f990 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
2f9a0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
2f9b0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
2f9c0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
2f9d0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
2f9e0 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
2f9f0 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
2fa00 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
2fa10 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
2fa20 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
2fa30 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
2fa40 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
2fa50 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
2fa60 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2fa70 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2fa80 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2fa90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2faa0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2fab0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2fac0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2fad0 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
2fae0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2faf0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
2fb00 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
2fb10 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
2fb20 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
2fb30 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
2fb40 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
2fb50 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
2fb60 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2fb70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2fb80 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2fb90 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
2fba0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
2fbb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2fbc0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
2fbd0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
2fbe0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
2fbf0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
2fc00 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
2fc10 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
2fc20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
2fc30 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
2fc40 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2fc50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2fc60 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
2fc70 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
2fc80 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
2fc90 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
2fca0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
2fcb0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
2fcc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2fcd0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2fce0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2fcf0 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
2fd00 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2fd10 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
2fd20 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2fd30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2fd40 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
2fd50 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
2fd60 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2fd70 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
2fd80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
2fd90 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
2fda0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
2fdb0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
2fdc0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
2fdd0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2fde0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
2fdf0 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
2fe00 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
2fe10 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
2fe20 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
2fe30 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
2fe40 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
2fe50 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
2fe60 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
2fe70 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
2fe80 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
2fe90 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
2fea0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
2feb0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
2fec0 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
2fed0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2fee0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
2fef0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
2ff00 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
2ff10 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
2ff20 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
2ff30 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
2ff40 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
2ff50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2ff60 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
2ff70 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
2ff80 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
2ff90 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
2ffa0 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
2ffb0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
2ffc0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
2ffd0 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
2ffe0 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
2fff0 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
30000 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
30010 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
30020 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
30030 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
30040 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
30050 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
30060 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
30070 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
30080 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
30090 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
300a0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
300b0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
300c0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
300d0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
300e0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
300f0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
30100 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
30110 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
30120 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
30130 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
30140 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
30150 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
30160 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
30170 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
30180 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
30190 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
301a0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
301b0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
301c0 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
301d0 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
301e0 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
301f0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
30200 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
30210 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
30220 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
30230 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
30240 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
30250 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
30260 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
30270 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
30280 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
30290 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
302a0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
302b0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
302c0 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
302d0 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
302e0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
302f0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
30300 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
30310 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
30320 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
30330 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
30340 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
30350 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
30360 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
30370 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
30380 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
30390 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
303a0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
303b0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
303c0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
303d0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
303e0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
303f0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
30400 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30410 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
30420 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30430 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
30440 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
30450 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
30460 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
30470 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
30480 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
30490 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
304a0 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
304b0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
304c0 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
304d0 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
304e0 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
304f0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
30500 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30510 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
30520 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
30530 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
30540 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
30550 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
30560 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
30570 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
30580 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
30590 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
305a0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
305b0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
305c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
305d0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
305e0 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
305f0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
30600 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
30610 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
30620 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
30630 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
30640 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
30650 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
30660 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
30670 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
30680 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
30690 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
306a0 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
306b0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
306c0 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
306d0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
306e0 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
306f0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
30700 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
30710 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
30720 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
30730 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30740 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
30750 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
30760 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
30770 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
30780 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76  ().  But after v
30790 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
307a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
307b0 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
307c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
307d0 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
307e0 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
307f0 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
30800 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
30810 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
30820 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
30830 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
30840 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
30850 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
30860 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
30870 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
30880 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
30890 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
308a0 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
308b0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
308c0 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
308d0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
308e0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
308f0 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
30900 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
30910 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
30920 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
30930 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
30940 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
30950 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
30960 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
30970 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
30980 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
30990 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
309a0 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
309b0 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
309c0 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
309d0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
309e0 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
309f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
30a00 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
30a10 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
30a20 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
30a30 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
30a40 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
30a50 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
30a60 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
30a70 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
30a80 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
30a90 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
30aa0 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
30ab0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
30ac0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
30ad0 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
30ae0 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
30af0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
30b00 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
30b10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
30b20 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
30b30 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
30b40 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
30b50 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
30b60 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
30b70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
30b80 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
30b90 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
30ba0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
30bb0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
30bc0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
30bd0 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
30be0 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
30bf0 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
30c00 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
30c10 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  mended..*/.SQLIT
30c20 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
30c30 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
30c40 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
30c50 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
30c60 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
30c70 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
30c80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
30c90 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
30ca0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
30cb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
30cc0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
30cd0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
30ce0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
30cf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30d00 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
30d10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30d20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
30d30 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
30d40 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
30d50 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
30d60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
30d70 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
30d80 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
30d90 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
30da0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
30db0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
30dc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
30dd0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
30de0 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
30df0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
30e00 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
30e10 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
30e20 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
30e30 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
30e40 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
30e50 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
30e60 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
30e70 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
30e80 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
30e90 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
30ea0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
30eb0 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
30ec0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
30ed0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
30ee0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
30ef0 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
30f00 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
30f10 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
30f20 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
30f30 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
30f40 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
30f50 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
30f60 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
30f70 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
30f80 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
30f90 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
30fa0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
30fb0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  mn_count()].*/.S
30fc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
30fd0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
30fe0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
30ff0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
31000 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
31010 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
31020 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
31030 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
31040 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
31050 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
31060 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
31070 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
31080 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
31090 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
310a0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
310b0 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
310c0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
310d0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
310e0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
310f0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
31100 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
31110 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
31120 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
31130 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
31140 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
31150 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
31160 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
31170 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
31180 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
31190 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
311a0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
311b0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
311c0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
311d0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
311e0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
311f0 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
31200 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
31210 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
31220 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
31230 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
31240 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
31250 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
31260 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
31270 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
31280 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
31290 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
312a0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
312b0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
312c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
312d0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
312e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
312f0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
31300 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
31310 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
31320 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
31330 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
31340 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
31350 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
31360 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
31370 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61  ult set" interfa
31380 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ce..**.** ^These
31390 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
313a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
313b0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
313c0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
313d0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
313e0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
313f0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
31400 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
31410 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
31420 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
31430 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
31440 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
31450 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
31460 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
31470 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
31480 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
31490 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
314a0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
314b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
314c0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
314d0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
314e0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
314f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
31500 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
31510 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
31520 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
31530 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
31540 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
31550 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
31560 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
31570 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
31580 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
31590 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
315a0 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
315b0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
315c0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
315d0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
315e0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
315f0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
31600 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
31610 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
31620 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
31630 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
31640 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
31650 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
31660 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
31670 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
31680 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
31690 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
316a0 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
316b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
316c0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
316d0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
316e0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
316f0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
31700 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
31710 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
31720 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
31730 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
31740 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31750 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
31760 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
31770 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
31780 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
31790 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
317a0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
317b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
317c0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
317d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
317e0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
317f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
31800 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
31810 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
31820 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
31830 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
31840 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
31850 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
31860 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
31870 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
31890 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
318a0 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
318b0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
318c0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
318d0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
318e0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
318f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
31900 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
31910 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
31920 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
31930 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
31940 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
31950 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
31960 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
31970 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
31980 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
31990 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
319a0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
319b0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
319c0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
319d0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
319e0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
319f0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
31a00 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
31a10 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
31a20 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
31a30 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
31a40 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
31a50 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
31a60 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
31a70 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
31a80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31a90 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
31aa0 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
31ab0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
31ac0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
31ad0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
31ae0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
31af0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31b00 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
31b10 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
31b20 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
31b30 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
31b40 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
31b50 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
31b60 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
31b70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31b80 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
31b90 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
31ba0 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
31bb0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
31bc0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
31bd0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
31be0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
31bf0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
31c00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
31c10 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
31c20 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
31c30 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
31c40 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
31c50 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
31c60 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
31c70 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
31c80 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
31c90 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
31ca0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
31cb0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
31cc0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
31cd0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
31ce0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
31cf0 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
31d00 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
31d10 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
31d20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31d30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
31d40 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
31d50 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
31d60 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
31d70 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
31d80 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
31d90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
31da0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
31db0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
31dc0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
31dd0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
31de0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
31df0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
31e00 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
31e10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31e20 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
31e30 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
31e40 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
31e50 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
31e60 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
31e70 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
31e80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
31e90 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
31ea0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
31eb0 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
31ec0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
31ed0 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
31ee0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
31ef0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
31f00 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
31f10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
31f20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
31f30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
31f40 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
31f50 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
31f60 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
31f70 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
31f80 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
31f90 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
31fa0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
31fb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31fc0 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
31fd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
31fe0 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
31ff0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
32000 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
32010 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
32020 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
32030 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
32040 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
32050 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
32060 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
32070 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
32080 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
32090 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
320a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
320b0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
320c0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
320d0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
320e0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
320f0 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
32100 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
32110 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
32120 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
32130 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
32140 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
32150 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32160 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
32170 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
32180 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
32190 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
321a0 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
321b0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
321c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
321d0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
321e0 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
321f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
32200 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
32210 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
32220 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
32230 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
32240 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
32250 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
32260 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
32270 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
32280 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
32290 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
322a0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
322b0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
322c0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
322d0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
322e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
322f0 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
32300 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
32310 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
32320 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
32330 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
32340 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
32350 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
32360 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
32370 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
32380 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
32390 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
323a0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
323b0 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
323c0 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
323d0 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
323e0 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
323f0 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
32400 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
32410 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
32420 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
32430 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
32440 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
32450 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
32460 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
32470 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
32480 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
32490 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
324a0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
324b0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
324c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
324d0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
324e0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
324f0 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
32500 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
32510 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
32520 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
32530 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
32540 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
32550 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
32560 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
32570 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
32580 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
32590 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
325a0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
325b0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
325c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
325d0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
325e0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
325f0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
32600 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
32610 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
32620 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
32630 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
32640 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
32650 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
32660 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
32670 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
32680 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
32690 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
326a0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
326b0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
326c0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
326d0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
326e0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
326f0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
32700 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
32710 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
32720 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
32730 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
32740 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
32750 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
32760 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
32770 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
32780 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
32790 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
327a0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
327b0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
327c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
327d0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
327e0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
327f0 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
32800 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
32810 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
32820 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
32830 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
32840 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
32850 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
32860 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
32870 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
32880 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
32890 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
328a0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  e>)^.**.** The t
328b0 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
328c0 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
328d0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
328e0 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
328f0 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
32900 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
32910 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
32920 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
32930 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
32940 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
32950 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
32960 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
32970 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
32980 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
32990 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
329a0 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
329b0 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
329c0 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
329d0 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
329e0 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
329f0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
32a00 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
32a10 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
32a20 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
32a30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
32a40 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
32a50 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
32a60 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
32a70 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
32a80 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
32a90 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
32aa0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
32ab0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
32ac0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
32ad0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
32ae0 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
32af0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
32b00 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
32b10 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
32b20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
32b30 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
32b40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
32b50 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
32b60 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
32b70 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
32b80 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
32b90 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
32ba0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
32bb0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
32bc0 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
32bd0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
32be0 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
32bf0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
32c00 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
32c10 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
32c20 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
32c30 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
32c40 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
32c50 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
32c60 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
32c70 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
32c80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32c90 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
32ca0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
32cb0 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
32cc0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
32cd0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
32ce0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
32cf0 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
32d00 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
32d10 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
32d20 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
32d30 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
32d40 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
32d50 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
32d60 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
32d70 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
32d80 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
32d90 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
32da0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
32db0 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
32dc0 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
32dd0 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
32de0 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
32df0 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
32e00 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
32e10 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
32e20 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
32e30 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
32e40 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
32e50 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
32e60 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
32e70 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
32e80 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
32e90 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
32ea0 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
32eb0 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
32ec0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
32ed0 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
32ee0 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
32ef0 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
32f00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32f10 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
32f20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32f30 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
32f40 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
32f50 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
32f60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
32f70 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
32f80 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
32f90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
32fa0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
32fb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32fc0 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
32fd0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
32fe0 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
32ff0 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
33000 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
33010 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
33020 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
33030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33040 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
33050 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
33060 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
33070 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
33080 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
33090 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
330a0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
330b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
330c0 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
330d0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
330e0 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
330f0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
33100 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
33110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33120 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
33130 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
33140 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
33150 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
33160 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
33170 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33180 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
33190 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
331a0 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
331b0 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
331c0 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
331d0 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
331e0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
331f0 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
33200 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
33210 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
33220 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
33230 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
33240 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
33250 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
33260 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
33270 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
33280 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
33290 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
332a0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
332b0 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
332c0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
332d0 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
332e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
332f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33300 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
33310 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
33320 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
33330 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
33340 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
33350 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
33360 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
33370 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
33380 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
33390 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
333a0 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
333b0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
333c0 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
333d0 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
333e0 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
333f0 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
33400 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
33410 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
33420 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
33430 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
33440 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
33450 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
33460 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
33470 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
33480 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33490 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
334a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
334b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
334c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
334d0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
334e0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
334f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
33500 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33510 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
33520 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  I double sqlite3
33530 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
33540 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33550 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
33560 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
33570 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
33580 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
33590 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
335a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
335b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
335c0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
335d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
335e0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e  ITE_API const un
335f0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
33600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33610 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33620 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
33630 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
33640 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
33650 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
33660 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
33670 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
33680 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33690 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
336a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
336b0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
336c0 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
336d0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
336e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
336f0 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
33700 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
33710 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
33720 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
33730 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33740 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
33750 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
33760 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
33770 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
33780 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
33790 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
337a0 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
337b0 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
337c0 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69  o errors.** or i
337d0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
337e0 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76  is never been ev
337f0 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71  aluated, then sq
33800 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
33810 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49   returns.** SQLI
33820 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20  TE_OK.  ^If the 
33830 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
33840 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d  uation of statem
33850 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68  ent S failed, th
33860 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  en.** sqlite3_fi
33870 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e  nalize(S) return
33880 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  s the appropriat
33890 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
338a0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65  r.** [extended e
338b0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
338c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
338d0 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69  inalize(S) routi
338e0 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
338f0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
33900 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65  ring.** the life
33910 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61   cycle of [prepa
33920 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
33930 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74  :.** before stat
33940 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20  ement S is ever 
33950 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72  evaluated, after
33960 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
33970 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
33980 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61  3_reset()], or a
33990 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a  fter any call.**
339a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
339b0 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20  p()] regardless 
339c0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
339d0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
339e0 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  has.** completed
339f0 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a   execution..**.*
33a00 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  * ^Invoking sqli
33a10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f  te3_finalize() o
33a20 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
33a30 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
33a40 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  o-op..**.** The 
33a50 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
33a60 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20   finalize every 
33a70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33a80 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  ent] in order to
33a90 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72   avoid.** resour
33aa0 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73  ce leaks.  It is
33ab0 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f   a grievous erro
33ac0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
33ad0 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20  ation to try to 
33ae0 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65  use.** a prepare
33af0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  d statement afte
33b00 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
33b10 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73  nalized.  Any us
33b20 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a  e of a prepared.
33b30 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ** statement aft
33b40 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
33b50 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73  inalized can res
33b60 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
33b70 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61   and.** undesira
33b80 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63  ble behavior suc
33b90 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61  h as segfaults a
33ba0 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69  nd heap corrupti
33bb0 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  on..*/.SQLITE_AP
33bc0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  I int sqlite3_fi
33bd0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
33be0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
33bf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
33c00 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
33c10 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
33c20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
33c30 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
33c40 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
33c50 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
33c60 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
33c70 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
33c80 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
33c90 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
33ca0 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
33cb0 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
33cc0 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
33cd0 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
33ce0 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
33cf0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
33d00 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
33d10 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
33d20 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
33d30 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
33d40 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
33d50 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
33d60 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
33d70 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
33d80 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
33d90 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
33da0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
33db0 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
33dc0 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
33dd0 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
33de0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
33df0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
33e00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
33e10 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
33e20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33e30 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
33e40 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
33e50 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
33e60 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
33e70 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
33e80 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
33e90 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
33ea0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
33eb0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
33ec0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
33ed0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
33ee0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
33ef0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
33f00 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
33f10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33f20 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
33f30 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
33f40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
33f50 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
33f60 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
33f70 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
33f80 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
33f90 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
33fa0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
33fb0 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
33fc0 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
33fd0 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
33fe0 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
33ff0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
34000 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
34010 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
34020 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
34030 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
34040 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
34050 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
34060 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
34070 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
34080 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
34090 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
340a0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
340b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
340c0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
340d0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
340e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
340f0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
34100 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
34110 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
34120 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
34130 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
34140 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
34150 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
34160 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
34170 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
34180 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
34190 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
341a0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
341b0 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
341c0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
341d0 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
341e0 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
341f0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
34200 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
34210 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
34220 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
34230 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
34240 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
34250 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
34260 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
34270 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
34280 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
34290 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
342a0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
342b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
342c0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
342d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
342e0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
342f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
34300 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
34310 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
34320 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
34330 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
34340 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
34350 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34360 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
34370 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
34380 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
34390 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
343a0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
343b0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
343c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
343d0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
343e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
343f0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
34400 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
34410 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
34420 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
34430 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
34440 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
34450 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
34460 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
34470 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
34480 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
34490 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
344a0 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
344b0 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
344c0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
344d0 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
344e0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
344f0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
34500 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
34510 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
34520 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
34530 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
34540 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
34550 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
34560 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
34570 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
34580 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
34590 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
345a0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
345b0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
345c0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
345d0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
345e0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
345f0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
34600 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
34610 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
34620 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
34630 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
34640 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
34650 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
34660 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
34670 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
34680 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
34690 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
346a0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
346b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
346c0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
346d0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
346e0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
346f0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
34700 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
34710 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
34720 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
34730 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
34740 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66  rs.  Every SQL f
34750 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
34760 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61  tation must be a
34770 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
34780 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
34790 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
347a0 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
347b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
347c0 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
347d0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
347e0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
347f0 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63  her.  ^An applic
34800 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76  ation may.** inv
34810 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
34820 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
34830 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34840 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
34850 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
34860 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
34870 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
34880 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
34890 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
348a0 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
348b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
348c0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
348d0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
348e0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
348f0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
34900 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
34910 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
34920 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
34930 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
34940 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
34950 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
34960 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
34970 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
34980 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
34990 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
349a0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
349b0 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
349c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
349d0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
349e0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
349f0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
34a00 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
34a10 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
34a20 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
34a30 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
34a40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
34a50 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
34a60 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
34a70 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
34a80 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
34a90 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
34aa0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
34ab0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
34ac0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
34ad0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
34ae0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
34af0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
34b00 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
34b10 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
34b20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
34b30 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
34b40 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
34b50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
34b60 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
34b70 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
34b80 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
34b90 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
34ba0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
34bb0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
34bc0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
34bd0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
34be0 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
34bf0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
34c00 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
34c10 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
34c20 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
34c30 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
34c40 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
34c50 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
34c60 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
34c70 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
34c80 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
34c90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34ca0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34cb0 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
34cc0 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
34cd0 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
34ce0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
34cf0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
34d00 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
34d10 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
34d20 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
34d30 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
34d40 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
34d50 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
34d60 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
34d70 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
34d80 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
34d90 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
34da0 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
34db0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
34dc0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34dd0 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
34de0 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
34df0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
34e00 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
34e10 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
34e20 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
34e30 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
34e40 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
34e50 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
34e60 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
34e70 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
34e80 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
34e90 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34ea0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
34eb0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
34ec0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
34ed0 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
34ee0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
34ef0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
34f00 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
34f10 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
34f20 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
34f30 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
34f40 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
34f50 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
34f60 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
34f70 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
34f80 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
34f90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34fa0 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
34fb0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
34fc0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
34fd0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
34fe0 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
34ff0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
35000 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
35010 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
35020 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
35030 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
35040 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
35050 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
35060 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
35070 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
35080 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
35090 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
350a0 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
350b0 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
350c0 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
350d0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
350e0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
350f0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
35100 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
35110 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
35120 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
35130 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
35140 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
35150 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
35160 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
35170 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
35180 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
35190 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
351a0 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
351b0 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
351c0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
351d0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
351e0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
351f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35200 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
35210 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
35220 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35230 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
35240 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
35250 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
35260 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
35270 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
35280 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
35290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
352a0 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
352b0 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
352c0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
352d0 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
352e0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
352f0 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
35300 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
35310 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
35320 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
35330 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
35340 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
35350 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
35360 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
35370 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
35380 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
35390 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
353a0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
353b0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
353c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
353d0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
353e0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
353f0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
35400 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
35410 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
35420 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
35430 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
35440 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
35450 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
35460 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
35470 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
35480 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
35490 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
354a0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
354b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
354c0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
354d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
354e0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
354f0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
35500 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
35510 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
35520 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
35530 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35540 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
35550 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
35560 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
35570 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
35580 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
35590 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
355a0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
355b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
355c0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
355d0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
355e0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
355f0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
35600 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
35610 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
35620 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
35630 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
35640 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
35650 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
35660 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
35670 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
35680 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
35690 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
356a0 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
356b0 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
356c0 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
356d0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
356e0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
356f0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
35700 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
35710 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
35720 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
35730 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
35740 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
35750 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
35760 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
35770 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
35780 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
35790 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
357a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
357b0 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
357c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
357d0 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
357e0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
357f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
35800 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
35810 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
35820 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
35830 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
35840 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
35850 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
35860 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
35870 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
35880 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
35890 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
358a0 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
358b0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
358c0 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
358d0 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
358e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
358f0 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
35900 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
35910 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
35920 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
35930 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
35940 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
35950 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
35960 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
35970 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f  you what they do
35980 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
35990 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
359a0 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  TED.SQLITE_API S
359b0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
359c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
359d0 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
359e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
359f0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
35a00 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
35a10 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
35a20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
35a30 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
35a40 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
35a50 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
35a60 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
35a70 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
35a80 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
35a90 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
35aa0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
35ab0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
35ac0 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
35ad0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
35ae0 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
35af0 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
35b00 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
35b10 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
35b20 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
35b30 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
35b40 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
35b50 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
35b60 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
35b70 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71          void*,sq
35b80 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
35b90 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
35ba0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
35bb0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
35bc0 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
35bd0 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
35be0 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
35bf0 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
35c00 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
35c10 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
35c20 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
35c30 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
35c40 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
35c50 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
35c60 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
35c70 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
35c80 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
35c90 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
35ca0 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
35cb0 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
35cc0 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
35cd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35ce0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
35cf0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35d00 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
35d10 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
35d20 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
35d30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
35d40 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
35d50 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
35d60 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
35d70 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
35d80 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
35d90 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
35da0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
35db0 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
35dc0 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
35dd0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
35de0 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
35df0 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
35e00 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
35e10 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
35e20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
35e30 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
35e40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
35e50 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
35e60 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
35e70 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
35e80 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
35e90 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
35ea0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
35eb0 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
35ec0 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
35ed0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
35ee0 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
35ef0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
35f00 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
35f10 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
35f20 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
35f30 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
35f40 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
35f50 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
35f60 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
35f70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
35f80 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
35f90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
35fa0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
35fb0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
35fc0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
35fd0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
35fe0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
35ff0 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
36000 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
36010 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
36020 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
36030 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
36040 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
36050 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
36060 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
36070 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
36080 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
36090 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
360a0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
360b0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
360c0 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
360d0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
360e0 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
360f0 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
36100 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
36110 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
36120 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
36130 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
36140 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
36150 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
36160 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
36170 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
36180 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
36190 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
361a0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
361b0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
361c0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
361d0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
361e0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
361f0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
36200 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
36210 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
36220 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
36230 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
36240 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
36250 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
36260 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
36270 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
36280 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
36290 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
362a0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
362b0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
362c0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
362d0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
362e0 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
362f0 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
36300 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
36310 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
36320 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
36330 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
36340 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
36350 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
36360 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
36370 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
36380 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
36390 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
363a0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
363b0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
363c0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
363d0 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
363e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
363f0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
36400 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
36410 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
36420 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
36430 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
36440 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
36450 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
36460 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
36470 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
36480 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
36490 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rs..*/.SQLITE_AP
364a0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
364b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
364c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
364d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
364e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
364f0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
36500 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
36510 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
36520 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
36530 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
36540 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71  TE_API double sq
36550 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
36560 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
36570 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
36580 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
36590 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
365a0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
365b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
365c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
365d0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
365e0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
365f0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
36600 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
36610 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
36620 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
36630 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
36640 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
36650 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
36660 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
36670 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
36680 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
36690 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
366a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
366b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
366c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
366d0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
366e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
366f0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
36700 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
36710 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
36720 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
36730 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
36740 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
36750 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36760 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
36770 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
36780 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
36790 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
367a0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
367b0 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
367c0 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
367d0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
367e0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
367f0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
36800 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
36810 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
36820 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
36830 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
36840 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
36850 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
36860 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
36870 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
36880 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
36890 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
368a0 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
368b0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
368c0 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
368d0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
368e0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
368f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
36900 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
36910 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
36920 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
36930 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
36940 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
36950 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
36960 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
36970 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
36980 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
36990 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
369a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
369b0 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
369c0 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
369d0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
369e0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
369f0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
36a00 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
36a10 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
36a20 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
36a30 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
36a40 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
36a50 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
36a60 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
36a70 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
36a80 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
36a90 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
36aa0 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
36ab0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
36ac0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
36ad0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
36ae0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
36af0 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
36b00 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
36b10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
36b20 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
36b30 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
36b40 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
36b50 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72  ter .** when fir
36b60 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69  st called if N i
36b70 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  s less than or e
36b80 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
36b90 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  if a memory.** a
36ba0 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
36bb0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
36bc0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
36bd0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
36be0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
36bf0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
36c00 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
36c10 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
36c20 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
36c30 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
36c40 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
36c50 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
36c60 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
36c70 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
36c80 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
36c90 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
36ca0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
36cb0 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
36cc0 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
36cd0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
36ce0 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65  n.)^  Within the
36cf0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
36d00 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72  , it is customar
36d10 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20  y to set.** N=0 
36d20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  in calls to sqli
36d30 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
36d40 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68  ntext(C,N) so th
36d50 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c  at no .** pointl
36d60 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ess memory alloc
36d70 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a  ations occur..**
36d80 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
36d90 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
36da0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
36db0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
36dc0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
36dd0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
36de0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
36df0 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
36e00 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
36e10 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
36e20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
36e30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
36e40 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
36e50 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
36e60 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
36e70 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
36e80 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
36e90 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
36ea0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
36eb0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
36ec0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
36ed0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
36ee0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
36ef0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
36f00 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
36f10 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
36f20 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
36f30 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
36f40 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
36f50 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
36f60 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
36f70 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
36f80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36f90 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
36fa0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
36fb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
36fc0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
36fd0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
36fe0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
36ff0 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
37000 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
37010 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
37020 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
37030 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
37040 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
37050 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
37060 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
37070 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
37080 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
37090 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
370a0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
370b0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
370c0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
370d0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
370e0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
370f0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
37100 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37110 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37120 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
37130 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37140 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
37150 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
37160 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
37170 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
37180 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
37190 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
371a0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
371b0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
371c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
371d0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
371e0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
371f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37200 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
37210 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
37220 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
37230 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
37240 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
37250 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
37260 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
37270 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
37280 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
37290 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
372a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
372b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
372c0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
372d0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
372e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
372f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
37300 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
37310 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
37320 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
37330 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
37340 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
37350 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
37360 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
37370 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
37380 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
37390 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
373a0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
373b0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
373c0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
373d0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
373e0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
373f0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
37400 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
37410 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
37420 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
37430 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
37440 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
37450 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
37460 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
37470 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
37480 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
37490 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
374a0 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
374b0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
374c0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
374d0 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
374e0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
374f0 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
37500 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
37510 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
37520 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
37530 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
37540 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
37550 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
37560 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
37570 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
37580 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
37590 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
375a0 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
375b0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
375c0 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
375d0 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
375e0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
375f0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
37600 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
37610 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
37620 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
37630 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
37640 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
37650 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
37660 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
37670 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
37680 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
37690 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
376a0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
376b0 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
376c0 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
376d0 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
376e0 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
376f0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
37700 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
37710 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
37720 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
37730 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
37740 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
37750 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
37760 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
37770 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
37780 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
37790 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
377a0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
377b0 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
377c0 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
377d0 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
377e0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
377f0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
37800 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
37810 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
37820 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
37830 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
37840 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
37850 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
37860 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
37870 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
37880 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
37890 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
378a0 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
378b0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
378c0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
378d0 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
378e0 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
378f0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
37900 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
37910 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
37920 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
37930 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
37940 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
37950 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
37960 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
37970 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
37980 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
37990 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
379a0 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
379b0 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
379c0 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
379d0 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
379e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
379f0 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
37a00 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
37a10 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
37a20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
37a30 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
37a40 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
37a50 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
37a60 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
37a70 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
37a80 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
37a90 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
37aa0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
37ab0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
37ac0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
37ad0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
37ae0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
37af0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
37b00 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
37b10 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
37b20 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
37b30 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
37b40 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
37b50 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
37b60 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
37b70 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
37b80 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
37b90 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
37ba0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37bb0 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
37bc0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
37bd0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
37be0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
37bf0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
37c00 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
37c10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37c20 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
37c30 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
37c40 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
37c50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
37c60 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
37c70 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
37c80 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
37c90 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
37ca0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
37cb0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
37cc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
37cd0 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
37ce0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
37cf0 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
37d00 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
37d10 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
37d20 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
37d30 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
37d40 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
37d50 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
37d60 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
37d70 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
37d80 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
37d90 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
37da0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
37db0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
37dc0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
37dd0 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
37de0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
37df0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
37e00 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
37e10 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
37e20 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
37e30 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
37e40 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
37e50 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
37e60 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
37e70 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a  + compilers..*/.
37e80 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
37e90 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
37ea0 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
37eb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
37ec0 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
37ed0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
37ee0 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
37ef0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
37f00 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
37f10 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
37f20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37f30 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
37f40 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
37f50 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
37f60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
37f70 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
37f80 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
37f90 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
37fa0 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
37fb0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
37fc0 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
37fd0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
37fe0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
37ff0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
38000 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
38010 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
38020 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
38030 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
38040 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
38050 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
38060 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
38070 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
38080 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
38090 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
380a0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
380b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
380c0 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
380d0 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
380e0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
380f0 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
38100 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
38110 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
38120 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
38130 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
38140 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
38150 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
38160 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
38170 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
38180 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
38190 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
381a0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
381b0 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
381c0 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
381d0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
381e0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
381f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
38200 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
38210 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
38220 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
38230 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
38240 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
38250 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
38260 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
38270 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
38280 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
38290 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
382a0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
382b0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
382c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
382d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
382e0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
382f0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
38300 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
38310 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
38320 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
38330 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
38340 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
38350 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
38360 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
38370 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
38380 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
38390 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
383a0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
383b0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
383c0 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
383d0 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
383e0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
383f0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
38400 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
38410 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
38420 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
38430 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
38440 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
38450 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
38460 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
38470 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
38480 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
38490 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
384a0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
384b0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
384c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
384d0 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
384e0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
384f0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
38500 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
38510 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
38520 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
38530 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
38540 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
38550 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
38560 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
38570 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
38580 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
38590 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
385a0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
385b0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
385c0 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
385d0 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
385e0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
385f0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
38600 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
38610 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
38620 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
38630 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
38640 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
38650 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
38660 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
38670 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
38680 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
38690 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
386a0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
386b0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
386c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
386d0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
386e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
386f0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
38700 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
38710 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
38720 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
38730 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
38740 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
38750 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
38760 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
38770 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
38780 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
38790 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
387a0 6f 75 74 20 68 61 72 6d 2e